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.

ReferenceTypeDescription
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_typeString:
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

ReferenceTypeDescription
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
typeString:
• 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_configuration Fields

For 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

ReferenceDescription
namemycrm
display_nameMy 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_urlhttps://talkdeskapp.s3.amazonaws.com/assets/integrations/mycrm.png
icon_urlhttps://talkdeskapp.s3.amazonaws.com/assets/integrations/mycrm_icon.png
authentication_typecustom
authentication_configurationfield_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_endpointhttps://mycrm.example.org/auth_validation
contact_synchronization_endpointhttps://mycrm.example.org/contact_sync
interaction_retrieval_endpointhttps://mycrm.example.org/interaction_update
agent_synchronization_endpointhttps://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.

ReferenceTypeDescription
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

ReferenceTypeDescription
keyStringThe identifier of the field to send
nameStringThe name of the field to send
mandatoryBooleanTalkdesk won't execute the action if no value is given for mandatory fields
typeStringThe 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.
formatStringTemplate/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

ReferenceDescription
providerZendesk
namecreate_ticket
displayCreate a ticket
descriptionCreate a new ticket in Zendesk
endpointhttps://td-zendesk.herokuapp.com/actions/create_ticket
inputsA 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.

ReferenceTypeDescription
first_nameStringContact’s first name
last_nameStringContact’s last name
emailStringContact’s email address
phoneStringContact’s phone number
addressStringContact’s address
titleStringContact’s title
companyStringCompany associated with the contact
twitterStringContact’s twitter handle
linkedinStringContact’s LinkedIn handle
facebookStringContact’s Facebook handle
skypeStringContact's Skype handle
googleplusStringContact's GooglePlus handle
websiteTimeContact's website
industryStringContact's industry
locationStringContact's location
updated_atStringThe last time the contact was updated

🚧

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.