Create conversation

Create a new conversation for a workspace, optionally specifying an initial message to be sent.

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

Body

name*string

Name of the conversation. If it's an email channel, this will correspond to the email subject.

Example: "Re: Your refund request"

descriptionstring

Conversation description.

Example: "Refund request ticket"

visibilityenum

Whether the conversation is public or private.

publicprivate

accessibilityenum

Indicates the access level for new participants to join the conversation.

openinvite-onlyrequest-to-join

participantsarray of Conversations_ParticipantRef (object)

A list of up to 5 conversation participants.

channelId*string (uuid)

Channel ID.

Example: "ab651378-579a-4491-abe6-eec97d4c0fa3"

initialMessagenullable Conversations_CreateInitialMessage (object)

attributesnullable object

A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.

Other propertiesany

Response

The conversation is created

Body

id*string

Conversation ID.

Example: "299227f5-1c61-4341-ad50-efed5c048998"

name*string

Name of the conversation. If it's an email channel, this will correspond to the email subject.

Example: "Re: Your refund request"

descriptionstring

Conversation description.

Example: "Refund request ticket"

status*enum

Status of the conversation. Attempting to send messages in closed conversations results in an error.

activeclosed

visibility*enum

Whether the conversation is public or private.

publicprivate

accessibility*enum

Indicates the access level for new participants to join the conversation.

openinvite-onlyrequest-to-join

featuredParticipants*array of ConversationParticipant

A list of up to 5 conversation participants.

initiatingParticipantConversationParticipant

A participant who can send and receive messages in the conversation

activeParticipantCount*integer

Number of active participants.

Example: 2

pendingParticipantCountinteger

Number of participants who have requested to join the conversation with pending approval.

Example: 1

channelId*string (uuid)

Channel ID.

Example: "ab651378-579a-4491-abe6-eec97d4c0fa3"

lastMessageConversations_LastMessage (object)

Last message sent in this conversation.

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"

platformStyle*enum

The communication style of the platform. email represents an email channel; direct represents a 1:1 conversation, most channels will fall in this category, like WhatsApp and RCS; direct-multiple represents a channel that supports multiple conversations per contact, e.g. Chat; direct-threaded represents a threaded communication channel, e.g. Instagram Comments.

directemaildirect-multiple

attributesobject

A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.

referralConversations_Referral (object)

This represents a social media post or an ad that was referenced when starting the conversation.

likelySpamboolean

Whether this conversation was flagged as spam. Only present when anti-spam is enabled in the workspace settings.

likelySpamReasonstring

Reason for being flagged as spam.

Example: "advertisement"

Request

Response

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": "john.doe@bird.com"
    }
  ],
  "initialMessage": {
    "body": {
      "type": "text",
      "text": {
        "text": "Hey, listen!"
      }
    },
    "recipients": [
      {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "type": "to"
      }
    ]
  },
  "attributes": {
    "my-custom-attribute": "123"
  }
}'

{
  "id": "2280c45c-60d5-45a2-b51d-06ea752ca167",
  "name": "Email Subject",
  "description": "",
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "featuredParticipants": [
    {
      "id": "192c4449-9ccd-4747-8969-3bf07696af1c",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    {
      "id": "2d789fa4-85b7-4e59-b862-48062a0c0aa8",
      "type": "contact",
      "status": "active",
      "displayName": "John Doe",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com"
      }
    }
  ],
  "activeParticipantCount": 2,
  "pendingParticipantCount": 0,
  "initiatingParticipant": {
    "id": "192c4449-9ccd-4747-8969-3bf07696af1c",
    "type": "accessKey",
    "status": "active",
    "displayName": "My first email key",
    "avatarUrl": ""
  },
  "channelId": "25431165-c486-4a94-94f6-b3633c9af905",
  "lastMessage": {
    "id": "1c3a1c2d-2d27-4d5d-b7e4-ce62aecbba06",
    "type": "text",
    "preview": {
      "text": "Hey, listen!"
    },
    "recipients": [
      {
        "type": "to",
        "id": "2d789fa4-85b7-4e59-b862-48062a0c0aa8",
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com",
        "contactAnnotation": {
          "name": "John Doe"
        }
      }
    ],
    "status": "accepted",
    "sender": {
      "id": "192c4449-9ccd-4747-8969-3bf07696af1c",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    "createdAt": "2024-11-29T13:47:08.59Z"
  },
  "createdAt": "2024-11-29T13:47:08.546Z",
  "updatedAt": "2024-11-29T13:47:08.591Z",
  "platformStyle": "email",
  "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": "john.doe@bird.com"
    }
  ],
  "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": "john.doe@bird.com",
        "type": "to"
      }
    ]
  },
  "attributes": {
    "my-custom-attribute": "123"
  }
}'

{
  "id": "efec8397-c992-4195-9b1e-319b6ba8be26",
  "name": "Email Subject",
  "description": "",
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "featuredParticipants": [
    {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    {
      "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
      "type": "contact",
      "status": "active",
      "displayName": "John Doe",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com"
      }
    }
  ],
  "activeParticipantCount": 2,
  "pendingParticipantCount": 0,
  "initiatingParticipant": {
    "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
    "type": "accessKey",
    "status": "active",
    "displayName": "My first email key",
    "avatarUrl": ""
  },
  "channelId": "cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f",
  "lastMessage": {
    "id": "8849a1da-f8e9-41fa-8e60-8e12b1c6ed1a",
    "type": "html",
    "preview": {
      "text": ""
    },
    "recipients": [
      {
        "type": "to",
        "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com",
        "contactAnnotation": {
          "name": "John Doe"
        }
      }
    ],
    "status": "accepted",
    "sender": {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    "createdAt": "2024-12-02T13:42:06.876Z"
  },
  "createdAt": "2024-12-02T13:42:06.686Z",
  "updatedAt": "2024-12-02T13:42:06.877Z",
  "platformStyle": "email",
  "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"
  }
}'

{
  "id": "50a23da3-2ad9-42dd-94af-65b1b4271cb9",
  "name": "Ticket name",
  "description": "",
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "featuredParticipants": [
    {
      "id": "f9129db4-b39e-4dab-aa2f-e55904e90104",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first key",
      "avatarUrl": ""
    },
    {
      "id": "f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27",
      "type": "contact",
      "status": "active",
      "displayName": "John Doe",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "phonenumber",
        "identifierValue": "+31612345678",
        "platformAddress": "+31612345678"
      }
    }
  ],
  "activeParticipantCount": 2,
  "pendingParticipantCount": 0,
  "initiatingParticipant": {
    "id": "f9129db4-b39e-4dab-aa2f-e55904e90104",
    "type": "accessKey",
    "status": "active",
    "displayName": "My first key",
    "avatarUrl": ""
  },
  "channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
  "lastMessage": {
    "id": "25b3b6a2-7e1f-49ec-9371-b9a945fd6cec",
    "type": "list",
    "preview": {
      "text": "Message type 'list' was sent."
    },
    "recipients": [
      {
        "type": "to",
        "id": "f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27",
        "identifierKey": "phonenumber",
        "identifierValue": "+31612345678",
        "platformAddress": "+31612345678",
        "contactAnnotation": {
          "name": "John Doe"
        }
      }
    ],
    "status": "accepted",
    "sender": {
      "id": "f9129db4-b39e-4dab-aa2f-e55904e90104",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first key",
      "avatarUrl": ""
    },
    "createdAt": "2024-12-02T14:52:42.583Z"
  },
  "createdAt": "2024-12-02T14:52:42.484Z",
  "updatedAt": "2024-12-02T14:52:42.583Z",
  "platformStyle": "direct",
  "attributes": {
    "my-custom-attribute": "123"
  }
}

Last updated 19 days ago

{ "id": "299227f5-1c61-4341-ad50-efed5c048998", "name": "Re: Your refund request", "description": "Refund request ticket", "status": "active", "visibility": "public", "accessibility": "open", "featuredParticipants": [ { "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf", "displayName": "John Doe", "avatarUrl": "https://example.bird.com/avatar-url", "contact": { "identifierKey": "emailaddress", "identifierValue": "example@bird.com", "platformAddress": "example@bird.com", "platformAddressSelector": "attributes.workEmail" }, "type": "user", "status": "pending" } ], "initiatingParticipant": { "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf", "displayName": "John Doe", "avatarUrl": "https://example.bird.com/avatar-url", "contact": { "identifierKey": "emailaddress", "identifierValue": "example@bird.com", "platformAddress": "example@bird.com", "platformAddressSelector": "attributes.workEmail" }, "type": "user", "status": "pending" }, "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": "example@bird.com", "platformAddress": "example@bird.com", "platformAddressSelector": "attributes.workEmail" }, "type": "user", "status": "pending" }, "recipients": [ { "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf", "type": "to", "identifierKey": "emailaddress", "identifierValue": "example@bird.com", "platformAddress": "text", "platformAddressSelector": "attributes.workEmail", "contactAnnotation": { "name": "John Doe" } } ], "createdAt": "2024-01-01T00:00:00.123Z" }, "createdAt": "2024-01-01T00:00:00.123Z", "updatedAt": "2024-01-01T00:00:00.123Z", "platformStyle": "direct", "attributes": { "myCustomField": "abc" }, "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": false, "likelySpamReason": "advertisement" }