Configuring an Integration
Authentication Configuration
Depending on the external service you use to integrate with Talkdesk, some form of customer authentication might be necessary.
Talkdesk allows the integration to configure with authentication fields required from you. You can then use this information to identify the user and make authorized requests on their behalf to the external service.
Four authentication types can be used for an integration:
none: if no authentication information is necessary.custom: it asks the user for the authentication fields the bridge requires when the user first activates the integration for their account. The authentication fields are passed transparently to the bridge as authentication parameters when making requests for that user.oauth2: if the external service you are integrating with supports OAuth 2.0 user authentication, Talkdesk offers a simple way to ask the user for access to their account within the external service. This authentication type represents the Authorization Code Grant Type.oauth2_password: it is the same as OAuth 2.0 with the addition of username and password to authenticate with the authentication service. This authentication type represents the Password Grant Type.oauth2_client_credentials: it is the same as OAuth 2.0 password, but it uses the Client Credentials Grant Type which doesn't require username and password.
Integration Configuration
For an integration configuration to be created on the Talkdesk’s end, the data below must be provided.
| Reference | Type | Description |
|---|---|---|
name | • String. • Unique. • Mandatory. | The integration’s system name |
display_name | • String. • Mandatory. | A user-friendly name for the integration to be displayed in the interface |
description | • String. • Mandatory. | A user-friendly description of the service the integration is bridging to |
logo_url | • String. • Mandatory. | The URL location of the integration service logo to be displayed when configuring the integration |
icon_url | • String. • Mandatory. | The URL location of the integration service icon to be displayed for retrieved interactions within a contact |
authentication_type | String: • none.• custom.• oauth2.• oauth2_password.• oauth2_client_credentials. | The type of authentication to use: • If none is set, authentication_configuration is unnecessary.• For custom, oauth2, oauth2_password or oauth2_client_credentials, authentication fields must be set. |
auth_validation_endpoint | • String. • Optional. | The URL of the integration bridge responsible for validating if the given credentials authorize the user |
contact_synchronization_endpoint | • String. • Optional. | The URL of the integration bridge responsible for contact synchronization. If nil, contact synchronization features will not be available for the integration. |
interaction_retrieval_endpoint | • String. • Optional. | The URL of the integration bridge responsible for interaction retrieval. If nil, interaction retrieval features will not be available for the integration. |
agent_synchronization_endpoint | • String. • Optional. However, in cases where the integration necessitates CTI, agent_synchronization_endpoint is mandatory, as CTI functionality relies on it. | The URL of the integration bridge responsible for agent synchronization. If nil, agent synchronization features will not be available for the integration. |
interaction_types | • List. • Optional. | • A list of strings that identifies which types of interactions this integration can retrieve. • Each account will configure a subset of these types according to its interest. |
authentication_configuration | • List. • Optional when authentication_type is set to none.• Mandatory for custom, oauth2, oauth2_password or oauth2_client_credentials. | • Authentication fields required for the external integration's authentication process. • When requests are made to the external integration's bridge, the value to send for these fields is retrieved from the user account. |
authentication_configuration
authentication_configuration| Reference | Type | Description |
|---|---|---|
field_name | • String. • Unique within the element. | The name of the field to send |
display | • String. • Mandatory. | Display-friendly name when presenting the input on the interface |
mandatory | • Boolean. • Mandatory. | Talkdesk only validates mandatory fields |
type | String: • Text. • Password. • OAuth. | Instructing Talkdesk on how to obtain the field: • input for user provided fields.• oauth for fields provided by the OAuth 2.0 authority. |
store | • Boolean. • Mandatory. | • Controls if the field is to be stored in the configuration. • A use case for this is combining type OAuth with store false for field code when requiring Talkdesk to retrieve an OAuth code. |
help | • String. • Optional. | Hint to display along with the field, on the interface |
format | • String. • Optional. | Template to gather user input, allows a friendlier display on the interface (e.g.: if the field_name is username, it will be displayed as http://talkdesk.com/{{username}}) |
Mandatory
authentication_configurationFieldsFor oauth2
- site
- client_id
- client_secret
- authorization_url
- access_token_url
For oauth2_password
- site
- client_id
- client_secret
- username
- password
- access_token_url
For oauth2_client_credentials
- site
- client_id
- client_secret
- access_token_url
Examples
| Reference | Description |
|---|---|
name | mycrm |
display_name | My CRM |
description | • Centralizing all the customer conversations so nothing gets ignored and everything is searchable from one place. • Easily to organize, prioritize and engage with others on support requests. |
logo_url | https://talkdeskapp.s3.amazonaws.com/assets/integrations/mycrm.png |
icon_url | https://talkdeskapp.s3.amazonaws.com/assets/integrations/mycrm_icon.png |
authentication_type | custom |
authentication_configuration | •field_name: account• Display: Account • Mandatory: true • Type: input • Store: true • Help: under Settings > Account Format: https://{{account}}.example.org • field_name: token• Display: API Token • Mandatory: true • Type: input • Store: true • Help: under Settings > Channels |
auth_validation_endpoint | https://mycrm.example.org/auth_validation |
contact_synchronization_endpoint | https://mycrm.example.org/contact_sync |
interaction_retrieval_endpoint | https://mycrm.example.org/interaction_update |
agent_synchronization_endpoint | https://mycrm.example.org/agent_sync |
interaction_types | • Ticket. • Case. |
Actions Configuration
If an integration provides actions for Talkdesk to call, each of the actions has to provide a JSON configuration based on the references below.
| Reference | Type | Description |
|---|---|---|
provider | •String. •Mandatory. | The integration that provides this action (has to match the name attribute used to configure the integration). |
name | •String. •Mandatory. | Unique identifier of the action |
display | •String. •Mandatory. | User-friendly name for Talkdesk to use to identify the action to the user. It must be: •In lowercase, so that it can be used in the context of an automation (e.g.: Create a ticket as display is presented by Talkdesk as Then create a ticket). •Short, so that it can be used in a combo-box. |
description | •String. •Mandatory. | • User-friendly action description that Talkdesk shows the user. • It must be in lowercase, so that it can be used in the context of an automation (e.g.: Create a new ticket in Zendesk as description is presented by Talkdesk as Then create a new ticket in Zendesk). |
endpoint | •String. •Mandatory. | The URL of the integration bridge responsible for executing this action |
inputs | •List. •Mandatory. | A list of field definitions that this action can receive from Talkdesk in order to be executed in the third-party system |
inputs
inputs| Reference | Type | Description |
|---|---|---|
key | String | The identifier of the field to send |
name | String | The name of the field to send |
mandatory | Boolean | Talkdesk won't execute the action if no value is given for mandatory fields |
type | String | The type of input field. Valid values: • Text: one-line text box. Format: a default if no value is set. • Textarea: multiple line text box. Format: a default if no value is set. • Number: an integer. Format: a default if no value is set. • Tel: a phone number. Format: a default if no value is set. • URL: a URL. Format: a default if no value is set. • Datetime: a timestamp - acceptable formats: YYYY-MM-DD. YYYY-MM-DDTHH:mm:ss. YYYY-MM-DDTHH:mm:ssZ. • Select: a dropdown with pre-specified values, with values specified in a comma separated list. Format: Lakers,Bulls,Celtics. |
format | String | Template/default associated with the field type, value providers can be used for defaults. E.g.: if the field email should have the contact’s email as a default, {{contact.email}} can be specified. |
Examples
| Reference | Description |
|---|---|
provider | Zendesk |
name | create_ticket |
display | Create a ticket |
description | Create a new ticket in Zendesk |
endpoint | https://td-zendesk.herokuapp.com/actions/create_ticket |
inputs | A list of field definitions that this action can receive from Talkdesk in order to be executed in the third-party system |
Value Providers
Values coming from Talkdesk internal collections can be used as default values for action inputs. For the actions system to interpret these values, they must be enclosed in double curly brackets (e.g.: {{contact.first_name}}).
Contact Collection is an example of a value provider, of which, these values can be used.
| Reference | Type | Description |
|---|---|---|
first_name | String | Contact’s first name |
last_name | String | Contact’s last name |
email | String | Contact’s email address |
phone | String | Contact’s phone number |
address | String | Contact’s address |
title | String | Contact’s title |
company | String | Company associated with the contact |
twitter | String | Contact’s twitter handle |
linkedin | String | Contact’s LinkedIn handle |
facebook | String | Contact’s Facebook handle |
skype | String | Contact's Skype handle |
googleplus | String | Contact's GooglePlus handle |
website | Time | Contact's website |
industry | String | Contact's industry |
location | String | Contact's location |
updated_at | String | The last time the contact was updated |
Troubleshooting
If you have questions or technical issues, please open a ticket using this form.
Updated about 1 year ago