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:

• Using the contact ID
• Using channel recipient identities

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.

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.

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.

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.

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

{
  "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.

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

{
  "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

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:

• Sent message is connected with the most recently created contact.
• A contact channel identity duplication notification is sent via webhook, activating the CONTACT_IDENTITIES_DUPLICATION trigger.

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

{
  "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": ""
}

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.

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.

Channel identity is duplicated between existing contacts

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.

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

{
  "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": ""
}

Other sent messages and events examples

Channel recipient identity list contains identity value that matches existing contact, but for a different channel

If a channel identity value provided in a request matches the type (for example, a phone number) and value of an existing identity value that has been assigned to a different channel (for example, the phone number provided in a request to send a message on the SMS channel matches an existing phone number associated with the WhatsApp channel for a contact in the contact database), a new contact will be created after the request has been processed.

Channel recipient identity list contains a new app scoped identity, but also includes a project scoped identity that matches an existing contact

If a channel identity provided in a request contains a project-scoped channel identity that is already present in the database, but it also contains app-scoped identities which are not present in database, the existing contact will be updated with the new app-scoped identities. This is true even when the contact already contains app-scoped identities (associated with different apps) for the channels specified in the request.

Channel recipient identity list contains a project scoped identity that matches with an existing contact and an app scoped identity that conflicts with the existing contact

If a channel identity provided in a request contains a project-scoped channel identity that is already present in the database, but it also contains app-scoped identities that conflict with existing app-scoped identities assigned to the same contact:

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

Example Message Delivery Report with error message could be found here.