Conversations Messaging

Sending a message to an existing conversation

Create message in conversation

POST/workspaces/{workspaceId}/conversations/{conversationId}/messages

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The workspace ID

conversationId*any of

The conversation ID

enumstring (uuid)

Body

application/json

CreateMessage (one of)

MessageCreateWithBodyMessageCreateWithTemplate

Response

201403404409422

OK

Body

application/json

id*string

conversationIdstring

referencestring

sender*ConversationParticipant

draft*boolean

recipientsnullable array of MessageRecipient

status*MessageStatus (enum)

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

source*enum

conversationsexternal

templatenullable Template (object)

bodyMessageBody

reasonstring

interactionsnullable array of object

createdAt*string (date-time)

updatedAt*string (date-time)

metaMessageMeta

receiverTypesarray of enum

ReceiverTypes list of types of receivers for the message. It can be to, cc and bcc at the moment. Currently only use for inbound email platforms messages.

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/conversations/{conversationId}/messages', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "body": {
        "type": "text",
        "text": {
          "text": "text"
        }
      },
      "participantId": "text",
      "participantType": "user"
    }),
});
const data = await response.json();

Response

201403404409422

{
  "id": "text",
  "conversationId": "text",
  "reference": "text",
  "sender": {
    "id": "text",
    "displayName": "text",
    "avatarUrl": "text",
    "contact": {
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text"
    },
    "type": "user",
    "status": "pending"
  },
  "draft": false,
  "recipients": [
    {
      "id": "text",
      "type": "to",
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "contactAnnotation": {
        "name": "text"
      }
    }
  ],
  "status": "accepted",
  "source": "conversations",
  "template": {
    "name": "text",
    "projectId": "text",
    "version": "text",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": false
      }
    ],
    "shortLinks": {
      "enabled": false,
      "domain": "text"
    },
    "variables": {
      "default": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "whatsapp": {
          "previewUrl": false
        },
        "line": {
          "emoji": {
            "items": [
              {
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "reason": "text",
  "interactions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "read",
      "createdAt": "2024-11-21T08:51:40.395Z",
      "reason": "text",
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        }
      }
    }
  ],
  "createdAt": "2024-11-21T08:51:40.395Z",
  "updatedAt": "2024-11-21T08:51:40.395Z",
  "meta": {
    "email": {
      "subject": "text",
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "sourceId": "text",
        "sourceUrl": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "caption": "text",
        "username": "text",
        "timestamp": "2024-11-21T08:51:40.395Z",
        "trackingId": "text"
      }
    }
  },
  "receiverTypes": [
    "to"
  ]
}

Examples

Please refer to this link for examples of how to use the different templates for our supported platforms.https://app.gitbook.com/o/drwsqj0yXIErJc9wqqa2/s/dnJZeZvhOMhDQA8SpjQM/~/changes/309/channels-api/supported-channels

Sending a message template to an existing conversation

{
   "participantType":"user",
   "participantId":"8e1a962c-ecbe-47b3-8def-b0398c332232",
   "template":{
      "projectId":"897b53e7-fd4d-4324-b9b4-83bdeaaafbb4",
      "version":"0da60a7e-6a60-42e5-ab8b-a494f5185d30",
      "locale":"en",
      "parameters":[  
      ]
   },
}

Sending simple text messages

{
   "participantType":"user",
   "participantId":"8e1a962c-ecbe-47b3-8def-b0398c332232",
   "body":{
      "type":"text",
      "text":{
         "text":"Hi Daniel, how can I help you?"
      }
   },
}

Delete a message

DELETE/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The workspace ID

conversationId*any of

The conversation ID

enumstring (uuid)

messageId*string (uuid)

The message ID

Response

204404

Deleted

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

404

{
  "code": "ResourceNotFound",
  "message": "The requested resource does not exist"
}

List conversation messages

GET/workspaces/{workspaceId}/conversations/{conversationId}/messages

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The workspace ID

conversationId*any of

The conversation ID

enumstring (uuid)

Query parameters

Response

200404

OK

Body

application/json

resultsarray of Message (object)

nextPageTokenstring

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/conversations/{conversationId}/messages', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

200404

{
  "results": [
    {
      "id": "text",
      "conversationId": "text",
      "reference": "text",
      "sender": {
        "id": "text",
        "displayName": "text",
        "avatarUrl": "text",
        "contact": {
          "identifierKey": "text",
          "identifierValue": "text",
          "platformAddress": "text",
          "platformAddressSelector": "text"
        },
        "type": "user",
        "status": "pending"
      },
      "draft": false,
      "recipients": [
        {
          "id": "text",
          "type": "to",
          "identifierKey": "text",
          "identifierValue": "text",
          "platformAddress": "text",
          "platformAddressSelector": "text",
          "contactAnnotation": {
            "name": "text"
          }
        }
      ],
      "status": "accepted",
      "source": "conversations",
      "template": {
        "name": "text",
        "projectId": "text",
        "version": "text",
        "locale": "text",
        "attachments": [
          {
            "mediaUrl": "https://example.com",
            "filename": "text",
            "inline": false
          }
        ],
        "shortLinks": {
          "enabled": false,
          "domain": "text"
        },
        "variables": {
          "default": "text"
        },
        "utmParameters": [
          {
            "key": "text",
            "value": "text"
          }
        ],
        "parameters": [
          {
            "type": "string",
            "key": "text",
            "value": "text"
          }
        ]
      },
      "body": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": false
            }
          ],
          "actions": [
            {
              "type": "link",
              "link": {
                "text": "text",
                "url": "text"
              }
            }
          ],
          "metadata": {
            "subject": "text",
            "whatsapp": {
              "previewUrl": false
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "productId": "text",
                    "emojiId": "text"
                  }
                ]
              }
            },
            "telegram": {
              "parseMode": "Markdown"
            }
          }
        }
      },
      "reason": "text",
      "interactions": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "read",
          "createdAt": "2024-11-21T08:51:40.395Z",
          "reason": "text",
          "metadata": {
            "link": {
              "name": "text",
              "url": "text"
            },
            "button": {
              "payload": "text"
            },
            "reaction": {
              "emoji": "text",
              "action": "text"
            }
          }
        }
      ],
      "createdAt": "2024-11-21T08:51:40.395Z",
      "updatedAt": "2024-11-21T08:51:40.395Z",
      "meta": {
        "email": {
          "subject": "text",
          "from": {
            "username": "text",
            "displayName": "text"
          }
        },
        "referral": {
          "source": "text",
          "title": "text",
          "text": "text",
          "group": "text",
          "metadata": {
            "sourceId": "text",
            "sourceUrl": "text",
            "mediaType": "text",
            "mediaUrl": "text",
            "caption": "text",
            "username": "text",
            "timestamp": "2024-11-21T08:51:40.395Z",
            "trackingId": "text"
          }
        }
      },
      "receiverTypes": [
        "to"
      ]
    }
  ],
  "nextPageToken": "text"
}

Get a message

GET/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The workspace ID

conversationId*any of

The conversation ID

enumstring (uuid)

messageId*string (uuid)

The message ID

Response

200404

OK

Body

application/json

id*string

conversationIdstring

referencestring

sender*ConversationParticipant

draft*boolean

recipientsnullable array of MessageRecipient

status*MessageStatus (enum)

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

source*enum

conversationsexternal

templatenullable Template (object)

bodyMessageBody

reasonstring

interactionsnullable array of object

createdAt*string (date-time)

updatedAt*string (date-time)

metaMessageMeta

receiverTypesarray of enum

ReceiverTypes list of types of receivers for the message. It can be to, cc and bcc at the moment. Currently only use for inbound email platforms messages.

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

200404

{
  "id": "text",
  "conversationId": "text",
  "reference": "text",
  "sender": {
    "id": "text",
    "displayName": "text",
    "avatarUrl": "text",
    "contact": {
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text"
    },
    "type": "user",
    "status": "pending"
  },
  "draft": false,
  "recipients": [
    {
      "id": "text",
      "type": "to",
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "contactAnnotation": {
        "name": "text"
      }
    }
  ],
  "status": "accepted",
  "source": "conversations",
  "template": {
    "name": "text",
    "projectId": "text",
    "version": "text",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": false
      }
    ],
    "shortLinks": {
      "enabled": false,
      "domain": "text"
    },
    "variables": {
      "default": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "whatsapp": {
          "previewUrl": false
        },
        "line": {
          "emoji": {
            "items": [
              {
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "reason": "text",
  "interactions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "read",
      "createdAt": "2024-11-21T08:51:40.395Z",
      "reason": "text",
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        }
      }
    }
  ],
  "createdAt": "2024-11-21T08:51:40.395Z",
  "updatedAt": "2024-11-21T08:51:40.395Z",
  "meta": {
    "email": {
      "subject": "text",
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "sourceId": "text",
        "sourceUrl": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "caption": "text",
        "username": "text",
        "timestamp": "2024-11-21T08:51:40.395Z",
        "trackingId": "text"
      }
    }
  },
  "receiverTypes": [
    "to"
  ]
}

Update a message

PATCH/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The workspace ID

conversationId*any of

The conversation ID

enumstring (uuid)

messageId*string (uuid)

The message ID

Body

application/json

draftnullable boolean

bodyMessageBody

statusnullable enum

acceptedprocessingsentsending_faileddelivereddelivery_failed

Response

200404422

OK

Body

application/json

id*string

conversationIdstring

referencestring

sender*ConversationParticipant

draft*boolean

recipientsnullable array of MessageRecipient

status*MessageStatus (enum)

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

source*enum

conversationsexternal

templatenullable Template (object)

bodyMessageBody

reasonstring

interactionsnullable array of object

createdAt*string (date-time)

updatedAt*string (date-time)

metaMessageMeta

receiverTypesarray of enum

ReceiverTypes list of types of receivers for the message. It can be to, cc and bcc at the moment. Currently only use for inbound email platforms messages.

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404422

{
  "id": "text",
  "conversationId": "text",
  "reference": "text",
  "sender": {
    "id": "text",
    "displayName": "text",
    "avatarUrl": "text",
    "contact": {
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text"
    },
    "type": "user",
    "status": "pending"
  },
  "draft": false,
  "recipients": [
    {
      "id": "text",
      "type": "to",
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "contactAnnotation": {
        "name": "text"
      }
    }
  ],
  "status": "accepted",
  "source": "conversations",
  "template": {
    "name": "text",
    "projectId": "text",
    "version": "text",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": false
      }
    ],
    "shortLinks": {
      "enabled": false,
      "domain": "text"
    },
    "variables": {
      "default": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "whatsapp": {
          "previewUrl": false
        },
        "line": {
          "emoji": {
            "items": [
              {
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "reason": "text",
  "interactions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "read",
      "createdAt": "2024-11-21T08:51:40.395Z",
      "reason": "text",
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        }
      }
    }
  ],
  "createdAt": "2024-11-21T08:51:40.395Z",
  "updatedAt": "2024-11-21T08:51:40.395Z",
  "meta": {
    "email": {
      "subject": "text",
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "sourceId": "text",
        "sourceUrl": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "caption": "text",
        "username": "text",
        "timestamp": "2024-11-21T08:51:40.395Z",
        "trackingId": "text"
      }
    }
  },
  "receiverTypes": [
    "to"
  ]
}