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.

Integration Configuration

For an integration configuration to be created on the Talkdesk’s side, 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.

The type of authentication to use:
• If none is set, authentication_configuration is unnecessary.
• For custom, oauth2 or oauth2_password, 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.

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 or oauth2_password.

• 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

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_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

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

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


Did this page help you?