Configuring an event-driven integration
You follow this procedure to configure integrations using the event-driven integrations framework.
- In System Configurator, go to .
- Click Add New.
-
In the popup that opens, select the channel type of the integration:
-
Phone
-
Chat
-
Email: only supported for inbound conversations
This includes support for tasks and action items.
-
Multi-Channel: use only if you want to use the integration for several channels
-
- Enter a name and description for the integration.
- In the Endpoint URL field, enter the URL for the
connection to the web service. Currently, the only supported protocol is HTTPS.
You can use runtime data placeholders which will be replaced dynamically at
runtime using the data available from the
triggering event. For example:
- In https://external.rest.api/contact-pro-events/{event}, {event} will be replaced with the name of the event type.
- In https://external.rest.api/contact-pro-contacts/{contact.id}, {contact.id} will be replaced with the unique identifier of the contact.
To run a set operation based on a condition on data that has already been fetched with a previous integration, enter edi://echo as the endpoint URL. Read more about using echo in Example: Fetch customer data and use it on set operations based on a condition.
Note: You can define query parameters in the request part of JSON configuration. - In the Ordinal field, enter a number if there are several
integrations for the same conversations. This means the combination of queue(s),
direct calls and/or chats, and events. The integrations will be triggered in
this order. The maximum number of triggered integrations is three. If the same
operation is triggered in several integrations:
- The data in the save object is cumulated. Overlapping data is overwritten.
- A set operation is only run in the first integration that executes it successfully.
- In the Conversation Direction field, select the direction
of conversations where you want this integration to be used:
- Inbound
- Outbound
- Both
-
From the Conversation events that trigger this integration checkboxes, select when you'd like this integration to be triggered.
Table 1. Conversation events supported for each conversation type Event Description Chats in Chats out Calls in Calls out Emails Received The conversation has been received in Sinch Contact Pro but it hasn't been registered yet to an allocation queue. Queued The conversation has been registered to an allocation queue. Allocated The conversation has been allocated to an agent. Accepted The conversation has been accepted by an agent (inbound) or connected to an external party (outbound) Rejected The conversation has been rejected by an agent or its allocation cancelled by the system (inbound), or the call has been rejected by the external party (outbound) Transferred The conversation has been transferred to a queue or to another agent by an agent. Forwarded The conversation has been forwarded (overflowed) from one queue to another. Ended The conversation has ended after being connected to an agent (inbound) or an external party (outbound) Abandoned The conversation has ended without being connected to an agent (inbound) or an external party (outbound) -
Define in which conversations the integration is used:
-
In the Direct Conversations block, select if the integration is used in direct calls and direct chats. You can use the same integration in both direct and queue conversations.
-
In the Queues block, add the queues where the integration is used:
-
For chats, define the queue(s) from which messages are sent or to which they arrive. Define this for both inbound and outbound chats.
-
For calls, define the queue(s) for inbound queue calls.
-
-
-
In the Authentication block, define the credentials or access keys used with the web service.
Table 2. Authentication options Type Authentication ID Secret Basic basic:<username> Password Digest digest:<username> Password OAuth oauth:<client_id> Note: You must also defineclient_id in the authentication object in the JSON for Configuration field.Client secret Header value (for example, API key) Chosen name Secret To authenticate the integration to access the web service, you can refer to the authentication data you've defined in one of the following ways in your JSON:
- authentication type: When using basic authentication, use "authentication": {"type": "basic"}, .
- runtime data placeholder: refer to the secret part of your authentication details by specifying the request.headers property value as {"x-api-key": "{authentications.api-key}"}. In this example, authentication ID is "api-key". This resolves into the secret defined for the authentication.
-
In the JSON for Configuration field, define the JSON request for your integration. If you are adding an integration that also needs to return a response, define it here as well. The structure of the request and response is:
{ "request": { "authentication": [object], "method": [string], "headers": [object], "params": [object], "body": [object], }, "response": { "set": [object], "save": [object] } }
For more details, see how to build the request and how to build the response.
- Save the integration.
Copying an integration
To create a new integration by copying an existing one, click Copy.
Disabling an integration
To disable an integration, deselect all events.
Examples of integrations
Example: Fetch data from an external system and show it to the agent
Example: Listen to conversation lifecycle events