Create conversation
Create a new conversation for a workspace, optionally specifying an initial message to be sent.
Authorizations
Path parameters
workspaceIdstring · uuidRequiredExample:
The workspace ID
b4e02c85-c6d2-4b15-8885-e09671799c61
Body
all ofOptional
and
any ofOptional
or
Responses
201
The conversation is created
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
POST /workspaces/{workspaceId}/conversations HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1070
{
"name": "Re: Your refund request",
"description": "Refund request ticket",
"style": "default",
"visibility": "public",
"accessibility": "open",
"participants": [
{
"id": "986c5b08-3ec7-424a-a380-f3b41dc02746",
"type": "user"
}
],
"channelId": null,
"initialMessage": {
"reference": "my-own-business-logic-id-12345",
"sender": {
"name": "Bird Support",
"email": "[email protected]"
},
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"platformAddressSelector": "attributes.workEmail",
"type": "to"
}
],
"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"
}
}
}
},
"draft": false
},
"attributes": {
"myCustomField": "abc"
},
"resource": {
"type": "task",
"id": "123e4567-e89b-12d3-a456-426614174000"
},
"ANY_ADDITIONAL_PROPERTY": "anything"
}
{
"id": "299227f5-1c61-4341-ad50-efed5c048998",
"name": "Re: Your refund request",
"description": "Refund request ticket",
"status": "active",
"visibility": "public",
"accessibility": "open",
"style": "default",
"featuredParticipants": [
{
"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"
}
],
"initiatingParticipant": {
"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"
},
"activeParticipantCount": 2,
"pendingParticipantCount": 1,
"channelId": "ab651378-579a-4491-abe6-eec97d4c0fa3",
"lastMessage": {
"id": "69e97125-ddd4-4042-9d58-8350e806e1de",
"type": "text",
"preview": {
"text": "Thank you for reaching out, could you please inform your account number?"
},
"status": "accepted",
"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"
},
"recipients": [
{
"id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
"type": "to",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"platformAddress": "text",
"platformAddressSelector": "attributes.workEmail",
"contactAnnotation": {
"name": "John Doe"
}
}
],
"draft": true,
"createdAt": "2024-01-01T00:00:00.123Z"
},
"lastMessageIncomingAt": "2025-06-22T18:59:37.567Z",
"lastMessageOutgoingAt": "2025-06-22T18:59:37.567Z",
"createdAt": "2024-01-01T00:00:00.123Z",
"updatedAt": "2024-01-01T00:00:00.123Z",
"platformStyle": "direct",
"attributes": {
"myCustomField": "abc"
},
"summary": "Re: Your refund request",
"referral": {
"sourceUrl": "https://instagram.com/p/EXAMPLEID",
"sourceId": "120211000000000000",
"sourceType": "AD",
"mediaUrl": "https://cdninstagram.com/v/example",
"mediaType": "IMAGE",
"caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
"title": "Dream Summer Days Daily SPF",
"text": "Crafted with broad-spectrum SPF 50+ protection, Dream Summer Days Daily SPF offers reliable defense against both UVA and UVB rays",
"username": "DreamCosmetics",
"timestamp": "2024-11-28T12:00:00.000Z"
},
"likelySpam": true,
"likelySpamReason": "advertisement",
"resource": {
"type": "task",
"id": "123e4567-e89b-12d3-a456-426614174000"
},
"hasDraft": true
}
Examples
Starting a conversation with a simple message
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"name": "Email Subject",
"channelId": "25431165-c486-4a94-94f6-b3633c9af905",
"participants": [
{
"type": "contact",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]"
}
],
"initialMessage": {
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
},
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"type": "to"
}
]
},
"attributes": {
"my-custom-attribute": "123"
}
}'
Starting a conversation with an email template message
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"name": "Email Subject",
"channelId": "25431165-c486-4a94-94f6-b3633c9af905",
"participants": [
{
"type": "contact",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]"
}
],
"initialMessage": {
"template": {
"projectId": "5d9084b3-7cdb-4c87-bf7c-8871a1f21695",
"version": "b33761d9-ece1-48e3-b542-b5bbf93bd8c3",
"locale": "en",
"parameters": [
{
"type": "string",
"key": "myVariable",
"value": "yay"
}
]
},
"recipients": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"type": "to"
}
]
},
"attributes": {
"my-custom-attribute": "123"
}
}'
Starting a conversation with a WhatsApp template message
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"name": "Ticket name",
"channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
"participants": [
{
"type": "contact",
"identifierKey": "phonenumber",
"identifierValue": "+31612345678"
}
],
"initialMessage": {
"template": {
"projectId": "4720942c-9bde-4934-ab77-f600743894a1",
"version": "5c0e4db5-20f2-4224-86f4-fce052997608",
"locale": "en",
"parameters": [
{
"type": "string",
"key": "age",
"value": "20"
}
]
},
"recipients": [
{
"identifierKey": "phonenumber",
"identifierValue": "+31612345678",
"type": "to"
}
]
},
"attributes": {
"my-custom-attribute": "123"
}
}'
Last updated
Was this helpful?