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:
accessKey
A Bird API access key. This is what you'll commonly use when sending messages through the Conversations API
Access key ID
contact
A Bird contact
Contact ID
flow
A Bird flow
Flow ID
Sends a message in a conversation. The message content can be comprised of either body
or template
. Attempting to send as a participant that hasn't been added to the conversation results in an error unless the option addMissingParticipants
is set to true
. Attempting to send messages in a closed conversation results in an error.
The workspace ID
b4e02c85-c6d2-4b15-8885-e09671799c61
The conversation ID
67e4d358-ca94-421e-98b7-448860df9d33
OK
User has no access to the requested resource
The resource specified in the URL was not found
The resource already exists
The request body did not pass validation
POST /workspaces/{workspaceId}/conversations/{conversationId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2054
{
"draft": true,
"reference": "my-own-business-logic-id-12345",
"sender": {
"name": "Bird Support",
"email": "[email protected]",
"emailReplyToAddress": "[email protected]"
},
"participantId": "85762b7e-1e25-4648-8e06-27195433cfe2",
"replyToMessageId": "4fe755f0-3575-4a9e-b5d7-a184758af613",
"participantType": "user",
"participantContactIdentifierKey": "emailaddress",
"participantContactIdentifierValue": "text",
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"platformAddressSelector": "attributes.workEmail",
"type": "to"
}
],
"addMissingParticipants": true,
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true,
"contentId": "text"
}
],
"actions": [
{
"type": "link",
"link": {
"text": "text",
"url": "text"
}
}
],
"metadata": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"whatsapp": {
"previewUrl": true
},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text"
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
},
"replyTo": {
"id": "603cb5cd-c3f8-4f41-bc59-6a9216d06bc1",
"order": 0,
"type": "message"
},
"appendPreviousMessage": true,
"channelId": "38038a15-0dde-4114-a882-df4a0e8c98e8",
"participants": [
{
"id": "986c5b08-3ec7-424a-a380-f3b41dc02746",
"type": "user"
}
],
"name": "Re: Your refund request",
"description": "Refund request ticket",
"visibility": "public",
"accessibility": "open",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"meta": {
"email": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"from": {
"username": "john.doe",
"displayName": "John Doe"
}
},
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"referral": {
"source": "text",
"title": "text",
"text": "text",
"group": "text",
"metadata": {
"sourceId": "120211000000000000",
"sourceUrl": "https://instagram.com/p/EXAMPLEID",
"mediaType": "IMAGE",
"mediaUrl": "https://cdninstagram.com/v/example",
"caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
"username": "DreamCosmetics",
"timestamp": "2024-11-28T12:00:00.000Z",
"trackingId": "text"
}
}
}
}
{
"id": "aef328e7-6282-4268-a35b-4e5fd9033d2d",
"conversationId": "0c63be07-3e97-42a3-900a-47e538032b73",
"reference": "my-own-business-logic-id-12345",
"sender": {
"id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
"displayName": "John Doe",
"avatarUrl": "https://example.bird.com/avatar-url",
"contact": {
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"platformAddress": "[email protected]",
"platformAddressSelector": "attributes.workEmail"
},
"type": "user",
"status": "active"
},
"draft": true,
"draftMeta": {
"creatorType": "bot"
},
"replyToMessageId": "123e4567-e89b-12d3-a456-426614174000",
"recipients": [
{
"id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
"type": "to",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"platformAddress": "text",
"platformAddressSelector": "attributes.workEmail",
"contactAnnotation": {
"name": "John Doe"
},
"isInbox": true
}
],
"status": "accepted",
"source": "conversations",
"template": {
"name": "text",
"projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"locale": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"shortLinks": {
"enabled": true,
"domain": "text"
},
"variables": {
"default": "text",
"ANY_ADDITIONAL_PROPERTY": "text"
},
"utmParameters": [
{
"key": "text",
"value": "text"
}
],
"parameters": [
{
"type": "string",
"key": "text",
"value": "text"
}
],
"settings": {
"useMmLite": true
}
},
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true,
"contentId": "text"
}
],
"actions": [
{
"type": "link",
"link": {
"text": "text",
"url": "text"
}
}
],
"metadata": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"whatsapp": {
"previewUrl": true
},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
},
"reason": "Insufficient credit",
"interactions": [
{
"id": "29f3aab3-ecd7-4a8c-92d3-c3366cfedd79",
"type": "read",
"createdAt": "2024-01-01T00:00:00.123Z",
"metadata": {
"link": {
"name": "text",
"url": "text"
},
"button": {
"payload": "text"
},
"reaction": {
"emoji": "text",
"action": "text"
},
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"createdAt": "2024-01-01T00:00:00.123Z",
"updatedAt": "2024-01-01T00:00:00.123Z",
"meta": {
"email": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"from": {
"username": "john.doe",
"displayName": "John Doe"
}
},
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"referral": {
"source": "text",
"title": "text",
"text": "text",
"group": "text",
"metadata": {
"sourceId": "120211000000000000",
"sourceUrl": "https://instagram.com/p/EXAMPLEID",
"mediaType": "IMAGE",
"mediaUrl": "https://cdninstagram.com/v/example",
"caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
"username": "DreamCosmetics",
"timestamp": "2024-11-28T12:00:00.000Z",
"trackingId": "text"
}
}
},
"receiverTypes": [
"to"
],
"inbox": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifier": "text",
"ownerId": "123e4567-e89b-12d3-a456-426614174000",
"ownerType": "user",
"type": "personal"
}
}
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": "[email protected]"
}
],
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
}
}'
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 '{
"participantType": "accessKey",
"participantId": "68b80b8d-8060-42df-bda3-73505a8fdb84",
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"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
}'
Last updated
Was this helpful?