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

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

Did this page help you?