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
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

Create message in conversation

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.

POSThttps://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages

Path parameters

workspaceId*string (uuid)

The workspace ID

Example: "b4e02c85-c6d2-4b15-8885-e09671799c61"

conversationId*string

The conversation ID

Example: "67e4d358-ca94-421e-98b7-448860df9d33"

Body

application/json

Conversations_CreateMessage (one of)

Message with bodyMessage with template

Response

201403404409422

OK

Body

application/json

id*string

Message ID.

Example: "aef328e7-6282-4268-a35b-4e5fd9033d2d"

conversationIdstring

Conversation ID.

Example: "0c63be07-3e97-42a3-900a-47e538032b73"

referencestring

A customizable ID assigned to messages you send. This can be used to correlate messages with data from your own integrating services. Must be globally unique within a workspace.

Example: "my-own-business-logic-id-12345"

sender*ConversationParticipant

A participant who can send and receive messages in the conversation

draft*boolean

Whether this message is a draft.

recipientsarray of MessageRecipient

Recipient list of this message.

status*Conversations_MessageStatus (enum)

Message status. The lifecycle order is accepted, processing, sent, and delivered.

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

source*enum

Whether the message was created by Bird's Conversations API or an external party.

Example: "conversations"

conversationsexternal

templatenullable Conversations_Template (object)

bodyMessageBody

reasonstring

Failure reason. Will be populated if the status is sending_failed or delivery_failed.

Example: "Insufficient credit"

interactionsnullable array of object

A list of interactions associated with the message.

createdAt*string (date-time)

Creation timestamp formatted as RFC3339.

Example: "2024-01-01T00:00:00.123Z"

updatedAt*string (date-time)

Update timestamp formatted as RFC3339.

Example: "2024-01-01T00:00:00.123Z"

metaMessageMeta

Message metadata fields that might be populated depending on the channel being used.

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('https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "body": {
        "type": "text",
        "text": {
          "text": "text"
        }
      },
      "participantId": "85762b7e-1e25-4648-8e06-27195433cfe2",
      "participantType": "user"
    }),
});
const data = await response.json();

Response

201403404409422

{
  "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": "[e-mail]",
      "platformAddress": "[e-mail]",
      "platformAddressSelector": "attributes.workEmail"
    },
    "type": "user",
    "status": "pending"
  },
  "draft": false,
  "recipients": [
    {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "type": "to",
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddress": "text",
      "platformAddressSelector": "attributes.workEmail",
      "contactAnnotation": {
        "name": "John Doe"
      }
    }
  ],
  "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": 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": [
              {
                "index": 0,
                "productId": "text",
                "emojiId": "text",
                "length": 0
              }
            ]
          }
        },
        "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"
        }
      }
    }
  ],
  "createdAt": "2024-01-01T00:00:00.123Z",
  "updatedAt": "2024-01-01T00:00:00.123Z",
  "meta": {
    "email": {
      "subject": "text",
      "from": {
        "username": "john.doe",
        "displayName": "John Doe"
      }
    },
    "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"
  ]
}

Examples

Sending a simple message

Request

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": "[e-mail]"
    }
  ],
  "body": {
    "type": "text",
    "text": {
      "text": "Hey, listen!"
    }
  }
}'

Response (201 - Created)

{
  "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": "[e-mail]",
      "platformAddress": "[e-mail]",
      "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

Request

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": "[e-mail]",
      "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
}'

Response (201 - Created)

{
  "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": "[e-mail]",
      "platformAddress": "[e-mail]",
      "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"
}