Contact Synchronization
Overview
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 fulfill 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. •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:
•synchronization_checkpoint and offset are sent with the value null (this corresponds to an initial sync situation and the bridge must retrieve all the contacts).
•An offset is sent with a null 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 a null 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 (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. |
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 |
custom_fields | Array of objects (optional) | Consists of an array of objects in the style of {"key": "Name of this custom field", "value": "Value of this custom field"} |
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 the 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 the 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]"],
"custom_fields":
[
{
"key": "My First Custom Field",
"value": "Value of this field"
},
{
"key": "My Second Custom Field",
"value": "Another value for this field"
}
]
}
]
}
Troubleshooting
There is a possibility that the volume of response data might be too high to process, leading to a failure. To avoid this, it's recommended to reduce the maximum number of contacts retrieved per request. Moreover, all requests are expected to take less than 10 seconds. If a request exceeds this limit, it will automatically fail.
If you have other questions or technical issues, please open a ticket using this form.
Updated 6 months ago