Conversation API contact management

When using the Conversation API in CONVERSATION mode (which is the intended usage mode for most Conversation API apps), the Conversation API automatically associates messages and conversations with contact entities. These contact entities contain various pieces of information, including the collection of related channel recipient identities.

When sending a mobile terminated (MT) message or event in CONVERSATION mode, you can identify the recipient in two ways:

Note:

When receiving mobile originated (MO) messages on the Conversation API, the sender is always identified by their channel recipient identity.

When the Conversation API processes message and event activity using channel recipient identities, it may encounter scenarios in which the corresponding contact information needs to be created, updated, or resolved against conflicting or duplicated information. This document explains the logic the Conversation API follows when completing those tasks.

Sending messages and events

The Conversation API allows you to send MT messages and events using channel recipient identities as contact identifiers. When doing so, the Conversation API may encounter and attempt to resolve the scenarios described in the sections below.

Channel recipient identities are connected to a single existing contact

If the contact database contains a single contact with channel recipient identities that match the identities provided in the request, the request will be connected to that contact.

Conversation API state comparison

Channel recipient identities are not connected to any existing contacts

If the channel recipient identities included in the request match none of the existing identities contained within the contacts in the contact database:

  • A new contact will be created. This contact will contain the channel recipient identities included in the request, and a contact creation notification will be sent.
  • The original request will be connected with the newly created contact.

Conversation API state comparison

Channel recipient identity list partially matches existing contact, but contains additional identities

If the contact database contains a contact with a channel recipient list that partially matches the channel recipient identities provided in request, and the additional identities provided in the request are not connected to any other contact:

  • The existing contact will be updated to include the additional channel recipient identities from request. A contact update notification will be sent.
    Note:

    When a contact is updated, the channel priority list is updated only if the contact already had a defined channel priority list. New channels are added to the end of the list in the order taken from request.

  • The original request will be connected with the updated contact.

Conversation API state comparison

Channel recipient identity list partially matches existing contact, but contains conflicts

If the contact database contains a contact with a channel recipient list that partially matches the channel recipient identities provided in the request, but at least one of the identities provided in the request conflicts with an identity contained in the contact:

  • Contact resolution will fail.
  • A delivery report with a FAILED status is sent via webhook, activating the MESSAGE_DELIVERY trigger.

Conversation API state comparison

An example of a delivery report that corresponds to this scenario is below:

Copy
Copied
{
  "app_id": "01F7QTFCAM1WAX0XJZ70EG1PCF",
  "accepted_time": "2021-10-03T07:37:20.146Z",
  "event_time": "2021-10-03T07:37:20.247073434Z",
  "project_id": "ee01a5a8-3945-4cf8-be4f-444698815ed5",
  "message_delivery_report": {
    "message_id": "01GEECE90J7NFMA75ND5YHQN14",
    "conversation_id": "",
    "status": "FAILED",
    "channel_identity": {
      "channel": "TELEGRAM",
      "identity": "12345678910",
      "app_id": ""
    },
    "contact_id": "",
    "reason": {
      "code": "BAD_REQUEST",
      "description": "Channel identity list provided in the request partially matches existing identity list for contact ID [01GE1HT5BS5PCMSM3WRENBBPHH], but includes conflicting identity values for the [RCS] channel(s). Please update the contact or recipient identity.",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Troubleshooting

To avoid this error in the future, you can do one of the following:

  • When sending messages or events to this recipient, ensure that the channel recipient identity list matches that of the existing contact.
  • Update the contact to match the channel identity list from request.
  • When sending messages or events to this recipient, identify them using their contact ID .

Channel recipient identities associate recipient with more than one contact

If different subsets of channel recipient identities provided in the request could connect the request to different contacts in the contact database:

  • Contact resolution will fail.
  • A delivery report with a FAILED status is sent via webhook, activating the MESSAGE_DELIVERY trigger.

Conversation API state comparison

An example of a delivery report that corresponds to this scenario is below:

Copy
Copied
{
  "app_id": "01F7QTFCAM1WAX0XJZ70EG1PCF",
  "accepted_time": "2021-10-03T08:28:32.468Z",
  "event_time": "2021-10-03T08:28:32.548673662Z",
  "project_id": "ee01a5a8-3945-4cf8-be4f-444698815ed5",
  "message_delivery_report": {
    "message_id": "01GEEFC1AMV10TTXMSBY58CE3F",
    "conversation_id": "",
    "status": "FAILED",
    "channel_identity": {
      "channel": "TELEGRAM",
      "identity": "12345678910",
      "app_id": ""
    },
    "contact_id": "",
    "reason": {
      "code": "BAD_REQUEST",
      "description": "Different channel identities provided in the request are associated with different contacts with the following contact IDs: [01GE1HT5BS5PCMSM3WRENBBPHH, 01GDWZK1SZ1VA26GQGDX0YNSQW]. Each channel identity can only be associated with one contact, and you can only message one contact at a time. Please update or merge your contacts, or edit your recipient identities, so that the request only identifies one existing contact.",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Troubleshooting

To avoid this error in the future, you can do one of the following:

  • When sending messages or events to this recipient, ensure that the channel recipient identity list matches only one existing contact.
  • Update the channel recipient identities of existing contacts to prevent the request from identifying more than one contact.
  • When sending messages or events to this recipient, identify them using their contact ID .

At least one channel recipient identity is duplicated between existing contacts

Note:

Project scoped channel identities are considered duplicates when they have the same channel and identity pair within the same project. App scoped channel identities are considered duplicates when they have the same app ID, channel, and identity combination within the same project.

If the request could be connected with more than one existing contact in the contact database because at least one channel recipient identity provided in the request is duplicated between the existing contacts:

  • Contact resolution will fail.
  • A delivery report with a FAILED status is sent via webhook, activating the MESSAGE_DELIVERY trigger.
  • A contact channel identity duplication notification is sent via webhook, activating the CONTACT_IDENTITIES_DUPLICATION trigger.

Conversation API state comparison

Examples of the notifications and delivery reports that correspond to this scenario are below:

CONTACT_IDENTITIES_DUPLICATION triggerMESSAGE_DELIVERY trigger
Copy
Copied
{
  "app_id": "01F7QTFCAM1WAX0XJZ70EG1PCF",
  "accepted_time": "2021-10-03T08:30:12.146125138Z",
  
  "event_time": "2021-10-03T08:30:12.146125138Z",
  "project_id": "ee01a5a8-3945-4cf8-be4f-444698815ed5",
  "duplicated_contact_identities_notification": {
    "duplicated_identities": [
      {
        "channel": "TELEGRAM",
        "contact_ids": [
          "01GE1HS14MGE2RNPP3XJP9463R",
          "01GE1HRVHG607WWQBDS5YE4M71"
        ]
      }
    ]
  },
  "message_metadata": ""
}
Copy
Copied
{
  "app_id": "01F7QTFCAM1WAX0XJZ70EG1PCF",
  "accepted_time": "2021-10-03T08:30:12.046Z",
  "event_time": "2021-10-03T08:30:12.184502840Z",
  "project_id": "ee01a5a8-3945-4cf8-be4f-444698815ed5",
  "message_delivery_report": {
    "message_id": "01GEEFF2JE3HJXBEXQZ90HJ9G8",
    "conversation_id": "",
    "status": "FAILED",
    "channel_identity": {
      "channel": "TELEGRAM",
      "identity": "12345678910",
      "app_id": ""
    },
    "contact_id": "",
    "reason": {
      "code": "BAD_REQUEST",
      "description": "Given identities belong to more than one contact. Duplicated identities found [Channel TELEGRAM- ContactIds [01GE1HS14MGE2RNPP3XJP9463R, 01GE1HRVHG607WWQBDS5YE4M71]]",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Troubleshooting

When a duplicate is identified, you must use the contact endpoint to resolve the issue for future requests. You can:

  • Delete one of the contacts that contains the duplicated channel recipient identities.
  • Update the contacts so that they no longer share duplicated channel recipient identities.
  • Merge the contacts that share duplicated channel recipient identities.
  • When sending messages or events, use a contact ID to identify the recipient.

Receiving messages

When the Conversation API receives an MO message while in CONVERSATION mode, it will connect that message with a contact. When doing so, the Conversation API may encounter and resolve the scenarios described in the sections below.

Channel identity is connected to a single existing contact

If the contact database contains a single contact with a channel recipient identity that matches the identity of the sender, the message will be connected to that contact.

Conversation API state comparison

Channel identity is not connected to any existing contacts

If the identity of the sender does not match any of the existing contacts in the contact database:

  • A new contact will be created. This contact will contain the channel identity of the sender, and a contact creation notification will be sent.
  • The original message will be connected with the newly created contact.

Conversation API state comparison

Channel identity is duplicated between existing contacts

Note:

Project scoped channel identities are considered duplicates when they have the same channel and identity pair within the same project. App scoped channel identities are considered duplicates when they have the same app ID, channel, and identity combination within the same project.

If the channel identity of the sender is duplicated between multiple contacts in the contact database:

  • The channel message is connected with the most recently created contact. This implementation allows the Conversation API to avoid dropping channel messages.
  • A contact channel identity duplication notification is sent via webhook, activating the CONTACT_IDENTITIES_DUPLICATION trigger.

Conversation API state comparison

An example of a notification that corresponds to this scenario is below:

Copy
Copied
{
  "app_id": "01F7QTFCAM1WAX0XJZ70EG1PCF",
  "accepted_time": "2021-10-03T08:30:12.146125138Z",
  "event_time": "2021-10-03T08:30:12.146125138Z",
  "project_id": "ee01a5a8-3945-4cf8-be4f-444698815ed5",
  "duplicated_contact_identities_notification": {
    "duplicated_identities": [
      {
        "channel": "RCS",
        "contact_ids": [
          "01GE1HS14MGE2RNPP3XJP9463R",
          "01GE1HRVHG607WWQBDS5YE4M71"
        ]
      }
    ]
  },
  "message_metadata": ""
}
Note:

When a duplicate is identified, you must use the contact endpoint to resolve the issue for future reqeusts. The Contact Identities Duplication Notification points to the contacts which should be deleted, updated, or merged to resolve the duplication issue.

Was this page helpful?
Still have a question? Ask the community.