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

post

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.

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 ofOptional

or

Responses

201

OK

application/json

403

User has no access to the requested resource

application/json

404

The resource specified in the URL was not found

application/json

409

The resource already exists

application/json

422

The request body did not pass validation

application/json

post

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/conversations/{conversationId}/messages HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1994

{
  "draft": true,
  "reference": "my-own-business-logic-id-12345",
  "sender": {
    "name": "Bird Support",
    "email": "[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
        }
      ],
      "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"
      }
    }
  ],
  "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
        }
      ],
      "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"
  ]
}

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": "[email protected]"
    }
  ],
  "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": "[email protected]",
      "platformAddress": "[email protected]",
      "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": "[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
}'

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": "[email protected]",
      "platformAddress": "[email protected]",
      "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"
}