Contact Activity

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

ReferenceTypeDescription
authHash•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.
metaHashA hash of meta fields containing accessory information that is useful for the bridge to fulfil this request
dataHash•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

ReferenceTypeDescription
meta.interaction_typesArrayAn array of strings that identifies the types of interactions the Talkdesk user is interested in

data

ReferenceTypeDescription
data.contact_external_idStringFor contacts previously synchronized through the bridge, Talkdesk sends their ID to the external service for direct identification
data.contact_nameStringThe contact's name
data.contact_emailsArrayAn array of emails that can be used to search for the user in the external service
data.contact_phonesArrayAn 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

ReferenceTypeDescription
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"
    }
]

🚧

Troubleshooting

If you have any questions, or if you’re having any technical issues, please open a ticket using this form.