Create conversation message
When sending messages through the Conversations API, the participant type must always be one of accessKey
, flow
, or contact
, with accessKey
being the most common usage. The value of participantId
depends on participantType
as shown below:
Participant type | Description | Meaning of participant ID |
---|---|---|
| A Bird API access key. This is what you'll commonly use when sending messages through the Conversations API | Access key ID |
| A Bird contact | Contact ID |
| A Bird flow | Flow ID |
Examples
Sending a simple message
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"participantType": "accessKey",
"participantId": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c",
"addMissingParticipants": true,
"recipients": [
{
"type": "to",
"identifierKey": "emailaddress",
"identifierValue": "some.customer@example.com"
}
],
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
}
}'
{
"id": "0c854061-6026-48c7-a2e8-bffb6458727b",
"conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
"reference": "",
"sender": {
"id": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c",
"type": "accessKey",
"status": "active",
"displayName": "My first email key",
"avatarUrl": ""
},
"draft": false,
"recipients": [
{
"type": "to",
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"identifierKey": "emailaddress",
"identifierValue": "some.customer@example.com",
"platformAddress": "some.customer@example.com",
"contactAnnotation": {
"name": "John Doe"
}
}
],
"status": "accepted",
"source": "conversations",
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
},
"interactions": null,
"createdAt": "2024-11-25T20:12:10.514Z",
"updatedAt": "2024-11-25T20:12:10.514Z"
}
Sending a template message
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"draft": true,
"participantType": "accessKey",
"participantId": "68b80b8d-8060-42df-bda3-73505a8fdb84",
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "john.doe@bird.com",
"type": "to"
}
],
"template": {
"projectId": "5d9084b3-7cdb-4c87-bf7c-8871a1f21695",
"version": "b33761d9-ece1-48e3-b542-b5bbf93bd8c3",
"locale": "en",
"parameters": [
{
"type": "string",
"key": "myVariable",
"value": "yay"
}
]
},
"addMissingParticipants": true
}'
{
"id": "cfd0877a-bc16-4e85-9f20-8996f2ebfa15",
"conversationId": "907798f8-fd72-44d5-8042-fcc05c1bb570",
"reference": "",
"sender": {
"id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
"type": "accessKey",
"status": "active",
"displayName": "My first email key",
"avatarUrl": ""
},
"draft": true,
"recipients": [
{
"type": "to",
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"identifierKey": "emailaddress",
"identifierValue": "john.doe@bird.com",
"platformAddress": "john.doe@bird.com",
"contactAnnotation": {
"name": "John Doe"
}
}
],
"status": "accepted",
"source": "conversations",
"template": {
"projectId": "5d9084b3-7cdb-4c87-bf7c-8871a1f21695",
"version": "b33761d9-ece1-48e3-b542-b5bbf93bd8c3",
"name": "",
"locale": "en",
"variables": null,
"shortLinks": null,
"parameters": [
{
"type": "string",
"key": "myVariable",
"value": "yay"
}
]
},
"body": {
"type": "html",
"html": {
"html": "<!DOCTYPE html><body><div>Hello, this is a test template with a variable: {{ myVariable | default: 'some default value' }}</div></body></html>",
"metadata": {
"subject": "Your email subject goes here."
}
}
},
"interactions": null,
"createdAt": "2024-12-02T13:22:45.736Z",
"updatedAt": "2024-12-02T13:22:45.736Z"
}
Last updated