Conversation Metadata

Telgorithm supports storing custom data with messages, known as Conversation Metadata. A conversation is identified by a pair of phone numbers, one of which is owned by your company. Currently, Conversation Metadata is not supported for Group MMS.

Setting Metadata

To specify Conversation Metadata, use the

property in the Send Outbound Message request:

Copy
{
  "from": "+10123456789",
  "to": "+19876543210",
  "text": "Glad to see you!",
  "conversationMetadata": "clientId=123", // sets conversation metadata
}

This metadata will be assigned to this message and future messages within this conversation.

Metadata Propagation

Conversation metadata is automatically propagated to subsequent messages in the same conversation. For example, if you send an Outbound Message with metadata and the recipient answers, the Inbound Message will receive the same metadata value. This ensures the persistence of metadata throughout the conversation. While metadata can be set multiple times, the new value affects only the message it was set for and subsequent messages in the conversation. Messages that have already been processed (queued, sent, failed, or received) will retain their original metadata value.

Getting Metadata

There are two ways to retrieve metadata for a message. Conversation metadata is automatically provided in Inbound or Outbound Message webhooks.

Outbound Message webhook example (some properties are omitted for brevity):

Copy
{
  "Sid": "OM08d9704f044a2fa13d3faa216fcf4574b64b19be32626243",
  "From": "+10123456789",
  "To": "+19876543210",
  ...
  "ConversationMetadata": "clientId=123" // metadata for this message
}

Any endpoint that returns Inbound or Outbound Messages supports the

query parameter. Setting this parameter to will provide conversation metadata in the response.

Example Request:

GET https://api.telgorithm.com/messaging/v1/InboundMessages?IncludeConversationMetadata=true

Example Response (some properties are omitted for brevity):

Copy
{
    "items": [
        {
            "sid": "IM08dbe4d588a100001d5155ca739071da5cdbe8aa81e9ad82",
            "from": "+19876543210",
            "to": "+10123456789",
            ...
            "conversationMetadata": "clientId=123", // metadata for this message
        }
    ],
    "searchId": null
}