Skip to main content

Contacts

Want to tie conversations across messaging channels to a single contact? Airy allows you to do that and then sync these contacts to your existing CRM solutions.

note

This feature is disabled by default. To enable it you need to set the integration.source-api.enabled field in your airy.yaml config to true.

Enabling the contacts component allows for this typical flow:

  • For every existing conversation we automatically create a contact that references the conversation
  • Contacts can then also be manually created, updated, fetched and importantly: merged

See the create contact response payload for an example of what the schema looks like.

Create contact#

POST /contacts.create

Sample request

All request fields are optional, but an empty payload will not be accepted.

{
"display_name": "Barabara Liskov",
"avatar_url": "https://example.org/avatar.jpg",
"title": "Professor",
"timezone": "", // relative to GMT
"gender": "female", // female, male or any other value
"locale": "en_US",
"organization_name": "Massachusetts Institute of Technology",
"via": {
"phone": "+1234567",
"email": "b.liskov@mit.org",
"key": "value" // allows for any additional key and value (arrays are prohibited)
},
"address": {
"organization_name": "Massachusetts Institute of Technology",
"address_line1": "77 Massachusetts Ave",
"address_line2": "building A",
"postcode": "02139",
"city": "Cambridge",
"state": "MA",
"country": "USA"
},
"conversations": {
// Automatically created contacts will always have a single conversation that is linked here
"ea1cba21-2bd6-477c-9a40-59cd9bb96bef": "facebook",
"8904adee-38b4-493b-a4d8-272e2e5a6815": "twilio.sms"
},
"metadata": {
"facebook": {
"psid": "1234567890",
"page_id": "9876543210"
},
"salesforce_id": "ABC123",
"zendesk_id": "XYZ789",
"key": "value" // allows for any additional key and value (arrays are prohibited)
}
}

(201) Success Response Payload

note

Refer to the Configuration Docs on how to input these values.

Create contact#

POST /contacts.list

This is a paginated endpoint.

Sample request

{
"cursor": "next-page-uuid",
"page_size": 2
}

Sample response

{
"data": [
{
"id": "6b80b10c-ae6e-4995-844d-c56c4da11623",
"display_name": "Barabara Liskov",
"title": "Professor",
"created_at": "2021-11-16T13:21:03.580Z"
},
{
"id": "c564cea4-a96f-4ebb-a220-3fb81b6ad522",
"display_name": "Grace Hopper",
"created_at": "2021-11-16T13:45:52.433Z"
}
],
"pagination_data": {
"previous_cursor": null,
"next_cursor": "2",
"total": 200
}
}

Get contact#

Get a single contact by contact or conversation id.

POST /contacts.info

Sample request by contact id

{
"id": "6b80b10c-ae6e-4995-844d-c56c4da11623"
}

Sample request by conversation id

{
"conversation_id": "ea1cba21-2bd6-477c-9a40-59cd9bb96bef"
}

Sample response

note

Refer to the Configuration Docs on how to input these values.

Update contact#

POST /contacts.update

All fields set on the creation request can be updated. To remove a field set it to the empty string "".

Sample request

{
"id": "6b80b10c-ae6e-4995-844d-c56c4da11623",
"display_name": "Barbara Liskov" //
}

Sample response 202 (Accepted)

Re-fetch contact#

POST /contacts.refetch

If there are conversations associated with this contact the sources will try to re-fetch the contact data that was ingested. This only works for messaging sources that allow you to pull contact data such as Facebook Messenger. Others like Google Business Messages will push new contact information, which will cause it to show up automatically.

Sample request

{
"contacts": ["6b80b10c-ae6e-4995-844d-c56c4da11623", "c564cea4-a96f-4ebb-a220-3fb81b6ad522"]
}

(202) Sample response

Merge contacts#

If you are sure two conversations belong to the same contact you can either:

  1. Call this endpoint if there are already contacts for both
  2. Update the either contact if the other does not exist
  3. Create a fresh contact if neither exist.

Calling this endpoint will cause the source contact to be deleted. However, calls to /contacts.info and /contacts.update will continue to be forwarded to the target contact.

Sample request

{
"source_contact": "6b80b10c-ae6e-4995-844d-c56c4da11623", // merge contact with this id
"target_contact": "c564cea4-a96f-4ebb-a220-3fb81b6ad522" // into contact with this id
}

Sample response

note

Refer to the Configuration Docs on how to input these values.

Delete contact#

Sample request

{
"id": "6b80b10c-ae6e-4995-844d-c56c4da11623"
}

(202) Sample response

Last updated on