Conversation Metadata

Conversation Metadata lets you attach custom data to messages and have it carry through a conversation. A conversation is identified by a pair of phone numbers, one of which is yours. Conversation Metadata isn't currently supported for Group MMS.

Setting metadata

Set the conversationMetadata property on a Send Outbound Message request:

{
  "from": "+10123456789",
  "to": "+19876543210",
  "text": "Glad to see you!",
  "conversationMetadata": "clientId=123"
}

This value is assigned to that message and every future message in the conversation.

Metadata propagation

We automatically carry conversation metadata forward to later messages in the same conversation. If you send an outbound message with metadata and the recipient replies, that inbound message gets the same metadata value. You can set new metadata at any point; the new value applies only to the message it's set on and messages after it. Messages already processed (queued, sent, failed, or received) keep whatever metadata they had at the time.

Getting metadata

There are two ways to retrieve a message's metadata.

It's included automatically in Inbound and Outbound Message webhooks:

{
  "Sid": "OM08d9704f044a2fa13d3faa216fcf4574b64b19be32626243",
  "From": "+10123456789",
  "To": "+19876543210",
  "ConversationMetadata": "clientId=123"
}

You can also request it from any endpoint that returns Inbound or Outbound Messages, by setting the IncludeConversationMetadata query parameter to true:

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

Example response (some fields omitted for brevity):

{
    "items": [
        {
            "sid": "IM08dbe4d588a100001d5155ca739071da5cdbe8aa81e9ad82",
            "from": "+19876543210",
            "to": "+10123456789",
            "conversationMetadata": "clientId=123"
        }
    ],
    "searchId": null
}