Overview

Contact activity allows displaying contact-related objects from your system on the relevant contact in Talkdesk's web app UI.

Talkdesk's interaction updater will send an HTTP POST request to the bridge to retrieve a contact's interactions with the external service whenever that contact is being displayed to a user. It passes along the parameters below.

Request

POST https://example.com/new_interaction

Reference	Type	Description
`auth`	Hash	•A hash of authentication fields containing a user's credentials within the external service. •The keys correspond to the fields asked by the integration when configuring it with Talkdesk.
`meta`	Hash	A hash of meta fields containing accessory information that is useful for the bridge to fulfil this request
`data`	Hash	•A hash of data fields identifying the contact for which the interaction retrieval request is made. •The bridge must use one or more of these to identify the contact in the external service.

meta

Reference	Type	Description
`meta.interaction_types`	Array	An array of strings that identifies the types of interactions the Talkdesk user is interested in

data

Reference	Type	Description
`data.contact_external_id`	String	For contacts previously synchronized through the bridge, Talkdesk sends their ID to the external service for direct identification
`data.contact_name`	String	The contact's name
`data.contact_emails`	Array	An array of emails that can be used to search for the user in the external service
`data.contact_phones`	Array	An array of phone numbers that can be used to search for the user in the external service

Steps

1 - Use the auth fields to authenticate on behalf of the user within the external service. Talkdesk® makes sure that all mandatory fields are filled as expected.

2 - Select the type of interactions to retrieve by looking at the interaction_types meta field.

3 - Make one or more requests to the external service to retrieve interactions from contacts identified by one or more of the data fields. These fields provide contact-related information that the bridge can use to identify the contact within the external service.

4 - Adapt these interactions to Talkdesk's format, by returning a JSON array with the structure below.

Sample Request

{
    "auth": {
        "username": "[email protected]",
        "password": "605b32dd"
    },
    "meta": {
        "interaction_types": ["case", "note"]
    },
    "data": {
        "contact_external_id": "1",
        "contact_name": "Jane",
        "contact_emails": ["[email protected]", "[email protected]"],
        "contact_phones": ["+15555555555"]
    }
}

Response

POST https://example.com/new_interaction

Reference	Type	Description
`id`	•String. •Unique. •Mandatory.	The interaction ID in the external service
`subject`	•String. •Mandatory.	The interaction subject or title
`description`	•String. •Optional.	A preview of the interaction (can be a text description or a preview of an email).
`date`	•String. •Mandatory.	The date this interaction occurred or its due date if it is a future interaction (like a task or event)
`url`	•String. •Optional.	URL location of this interaction in the external service
`type`	•String. •Mandatory.	•The type of interaction. •Must match one of the asked types in the request.
`priority`	•String. •None. •Low. •Normal. •High. •Urgent.	The interaction's level of urgency
`status`	•String •New. •Open. •Pending. •Solved. •Closed.	The current state of the interaction

Sample Response

[
    {
        "id":            "23",
        "subject":       "A very important matter",
        "description":   "Your order is ready to be shipped",
        "date":          "2012-11-21 17:53:51 UTC",
        "url":           "http://example.com/interactions/23",
        "type":          "case",
        "priority":      "high",
        "status":        "pending"
    }
]