Contact Synchronization

Overview

The contact synchronization allows bringing contacts from your system into Talkdesk® for proper caller identification and user attribution.

Talkdesk will send an HTTP POST to the bridge's configured endpoint when a contact synchronization is run. This request can be slightly different depending on the situation in which it is running:

Initial sync: the first time the contact synchronization runs for a given account, the bridge must retrieve every contact in the external system. When responding to the initial sync, the bridge can set a synchronization_checkpoint that Talkdesk will use from that moment on to only sync contacts incrementally.
Incremental sync: when a contact sync has been made and the bridge has set a synchronization_checkpoint in the response, Talkdesk will use that in the request that the bridge can use to only retrieve contacts updated after that checkpoint.
Next page: in both cases, when the external service only lets the bridge retrieve contacts in pages, the bridge must respond with the partially retrieved settings and set a next_offset in the response with the next page to retrieve. When this is set, Talkdesk will immediately make a new request with this value as the offset field within meta to retrieve the next page of contacts. This will be repeated until the bridge returns no next_offset in the response, meaning that all contacts have been retrieved.

Request

POST https://example.com/const_sync

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

meta

ReferenceTypeDescription
meta.synchronization_checkpoint•String.
•Mandatory.
•A generic starting point for the next synchronization with the third-party service.
•For initial synchronizations, this value will not be sent — which effectively means that the bridge should return all the contacts.
meta.offset•String.
•Optional.
•A generic offset the bridge should apply when retrieving paginated contacts.
•Can either return page numbers, absolute numerical offsets or some other form of result iteration.
•This parameter is omitted in the first call and is only sent if the bridge instructs the synchronizer that there are more records available.
meta.context•Value.
•Optional.
•A generic field that the bridge can use to keep transitional state between each paginated contacts fetch request.
•Can be any acceptable JSON value.
•This parameter is omitted on the first call and is only sent if the bridge both returns a value and instructs the synchronizer that there are more records available.

Sample Request

{
    "auth": {
        "username": "[email protected]",
        "password": "605b32dd"
    },
    "meta": {
        "offset": "2",
        "synchronization_checkpoint": "2012-11-20 23:01:00 UTC",
        "context": null
    }
}

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 - The bridge might be in one of the situations below (regarding contact retrieval), depending on the synchronization_checkpoint and offset parameters within meta if:
•No synchronization_checkpoint nor the offset are sent (this corresponds to an initial sync situation and the bridge must retrieve all the contacts).
•An offset is sent with no synchronization_checkpoint (it means that there are pages remaining to be retrieved for the initial sync. The bridge must get the next page of contacts).
•A synchronization_checkpoint is sent but with no offset (this corresponds to an incremental sync where only contacts updated after the synchronization_checkpoint must be retrieved).
•Both the synchronization_checkpoint and an offset are sent (this means there are pages remaining to be retrieved for the incremental sync, so the bridge must get the next page of contacts).

3 - Make a request to the external service and convert the result to Talkdesk's contact format, as displayed in the response below.

4 - Set the synchronization_checkpoint to mark the last synchronized contact. Next time Talkdesk synchronizes contacts, it will send along this value, so that the bridge can only retrieve contacts that were updated after this checkpoint. Talkdesk is completely agnostic to the meaning of this field. Bridges are responsible for selecting the best possible fit and for interpreting it.

5 - Set the next_offset field to the value of the next page of results when there are more contacts to retrieve. This will instruct Talkdesk's synchronizer that it needs to make another request to the bridge to retrieve the remaining contacts. Like synchronization_checkpoint, the system is agnostic to the meaning of this field. Bridges can either return page numbers, absolute numerical offsets or some other form of result iteration.

6 - The contacts must be sorted in ascending order of the field being used as a checkpoint, to ensure that Talkdesk has indeed synchronized all contacts from the external service until the moment characterized by the checkpoint. Next requests can be incremental (using a GET: all contacts updated after X semantics.

Response

POST https://example.com/const_sync

ReferenceTypeDescription
next_offsetString (optional)Value for next page offset, if there are more records that match the query
synchronization_checkpointString (optional)Synchronization checkpoint for this batch of results, resulting in an incremental request next time Talkdesk contact synchronization runs. If not set, all contacts from the external service will be retrieved on every synchronization.
contextValue (optional)Optional internal state to be sent in the next synchronizer request, if next_offset is set
contactsArrayAn array of hashes containing contacts sorted by ascending order by the field the bridge chose to mark as the synchornization_checkpoint

contacts

ReferenceTypeDescription
contacts.<element>.id•String.
•Unique.
•Mandatory.
Contact's ID in the external service
contacts.<element>.name•String.
•Mandatory.
Contact's full name
contacts.<element>.company•String.
•Optional.
Contact's company
contacts.<element>.title•String.
•Optional.
Contact's title within their company
contacts.<element>.emails•Array.
•Optional.
An array of strings containing contact's emails
contacts.<element>.phones•Array.
•Optional.
An array of strings containing contact's phone numbers
contacts.<element>.photo_url•String.
•Optional.
URL location of a contact's photo
contacts.<element>.address•String.
•Optional.
Contact's full address
contacts.<element>.websites•Array.
•Optional.
An array of strings containing contact's websites
contacts.<element>.twitter•String.
•Optional.
Contact's Twitter username
contacts.<element>.url•String.
•Optional.
URL location for the contact

Sample Response

{
    "next_offset": "3",
    "synchronization_checkpoint": "2012-12-01 11:21:00 UTC",
    "context": null,
    "contacts": [
        {
            "id":          "1",
            "name":        "Jane Doe",
            "title":       "CTO",
            "emails":      ["[email protected]", "[email protected]"],
            "phones":      ["+15555555555"],
            "photo_url":   "http://example.com/users/1/photo",
            "company":     "Example Corp.",
            "address":     "37, Famous St., New York, US",
            "websites":    ["www.example.com"],
            "twitter":     "jane_doe",
            "url":         "http://example.com/users/1/"
        },
        {
            "id":          "2",
            "name":        "Joe",
            "title":       "Staff",
            "emails":      ["[email protected]"]
        }
    ]
}

🚧

Troubleshooting

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