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

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

meta

Reference

Type

Description

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.
•Optoional.

•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

Reference

Type

Description

next_offset

String (optional)

Value for next page offset, if there are more records that match the query

synchronization_checkpoint

String (mandatory)

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.

context

Value (optional)

Optional internal state to be sent in the next synchronizer request, if next_offset is set

contacts

Array

An array of hashes containing contacts sorted by ascending order by the field the bridge chose to mark as the synchornization_checkpoint

contacts

Reference

Type

Description

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

Did this page help you?