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