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.

post

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

Authorizations

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdstring · uuidrequired

The workspace ID

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

conversationIdstringrequired

The conversation ID

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

Body

one of

A message specifying its contents through a body field.

A message specifying its contents through a template field.

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "draft": true,
    "reference": "my-own-business-logic-id-12345",
    "sender": {
      "name": "Bird Support",
      "email": "[e-mail]"
    },
    "participantId": "85762b7e-1e25-4648-8e06-27195433cfe2",
    "replyToMessageId": "4fe755f0-3575-4a9e-b5d7-a184758af613",
    "participantType": "user",
    "recipients": [
      {
        "identifierKey": "emailaddress",
        "identifierValue": "[e-mail]",
        "platformAddressSelector": "attributes.workEmail",
        "type": "to"
      }
    ],
    "addMissingParticipants": true,
    "body": {
      "type": "text",
      "text": {
        "text": "text",
        "actions": [
          {
            "type": "link",
            "link": {
              "text": "text",
              "url": "text"
            }
          }
        ],
        "attachments": [
          {
            "mediaUrl": "https://example.com",
            "filename": "text",
            "inline": true
          }
        ],
        "metadata": {
          "subject": "text",
          "telegram": {
            "parseMode": "Markdown"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "whatsapp": {
            "previewUrl": true
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "index": 1,
                  "productId": "text",
                  "emojiId": "text",
                  "length": 1
                }
              ]
            }
          }
        }
      }
    },
    "replyTo": {
      "id": "603cb5cd-c3f8-4f41-bc59-6a9216d06bc1",
      "order": 0,
      "type": "message"
    },
    "channelId": "38038a15-0dde-4114-a882-df4a0e8c98e8",
    "name": "Re: Your refund request",
    "description": "Refund request ticket",
    "attributes": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "meta": {
      "extraInformation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "email": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "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"
        }
      }
    },
    "visibility": "public",
    "accessibility": "open",
    "participants": [
      {
        "id": "986c5b08-3ec7-424a-a380-f3b41dc02746",
        "type": "user"
      }
    ]
  }'

201

403

404

409

422

201

{
  "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": "active"
  },
  "draft": true,
  "status": "accepted",
  "template": {
    "name": "text",
    "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "locale": "text",
    "parameters": [
      {
        "key": "text",
        "value": "text",
        "type": "string"
      }
    ],
    "shortLinks": {
      "enabled": true,
      "domain": "text"
    },
    "variables": {
      "default": "text",
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": true
      }
    ],
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true
        }
      ],
      "metadata": {
        "subject": "text",
        "telegram": {
          "parseMode": "Markdown"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        }
      }
    }
  },
  "reason": "Insufficient credit",
  "createdAt": "2024-01-01T00:00:00.123Z",
  "updatedAt": "2024-01-01T00:00:00.123Z",
  "meta": {
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "email": {
      "subject": "text",
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "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"
      }
    }
  },
  "source": "conversations",
  "recipients": [
    {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddress": "text",
      "platformAddressSelector": "attributes.workEmail",
      "type": "to",
      "contactAnnotation": {
        "name": "John Doe"
      }
    }
  ],
  "receiverTypes": [
    "to"
  ],
  "interactions": [
    {
      "id": "29f3aab3-ecd7-4a8c-92d3-c3366cfedd79",
      "createdAt": "2024-01-01T00:00:00.123Z",
      "type": "read",
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        },
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

OK

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