DokumentacjaEngagement Platform API
Sign inGet started
Guides
API

Create conversation

POST
/workspaces/{workspaceId}/conversations
Create a new conversation for a workspace, optionally specifying an initial message to be sent.
Treść żądania
name
string
wymagane
Name of the conversation. If it's an email channel, this will correspond to the email subject.
description
string
Conversation description.
style
string
Possible values: default, directMessage, chatChannel, personalInbox, resource, groupInbox, support
visibility
string
Possible values: public, private, direct, group
accessibility
string
Possible values: open, invite-only, request-to-join, private
participants
array of object
A list of up to 5 conversation participants.
Pokaż parametry podrzędne
Create a participant of the type user, access key, flow, agent, bot, or action rule.
participants.id
string
wymagane
The ID of the user, access key, flow, agent, bot, or action rule.
participants.type
string
wymagane
Participant type.
Possible values: user, accessKey, flow, agent, bot, collaborationAutomation
initiatingParticipant
object
The participant who initiated the conversation. When both initiatingParticipant and initialMessage are provided, the initial message sender takes precedence.
Pokaż parametry podrzędne
Create a participant of the type user, access key, flow, agent, bot, or action rule.
initiatingParticipant.id
string
wymagane
The ID of the user, access key, flow, agent, bot, or action rule.
initiatingParticipant.type
string
wymagane
Participant type.
Possible values: user, accessKey, flow, agent, bot, collaborationAutomation
channelId
wymagane
initialMessage
object
Pokaż parametry podrzędne
Initial message that will initiate the conversation.
initialMessage.reference
string
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.
initialMessage.sender
object
Message sender information for email.
Pokaż parametry podrzędne
initialMessage.sender.name
string
wymagane
Sender name shown in the email "From" header.
initialMessage.sender.email
string
Sender email address.
initialMessage.sender.emailReplyToAddress
string
Sender email address to reply to.
initialMessage.recipients
array of object
List of recipients.
Pokaż parametry podrzędne
Create a new recipient by specifying an identifier key and identifier value. For more information on identifier keys and values, please refer to the "Conversation Participants" page.
initialMessage.recipients.identifierKey
string
Identifier key of the contact depending on which channel is being used.
initialMessage.recipients.identifierValue
string
wymagane
Identifier of the contact, such as a phone number or email address.
initialMessage.recipients.platformAddressSelector
string
An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.
initialMessage.recipients.type
string
wymagane
Whether the email address is in the email's "To", "CC", or "BCC" headers.
Possible values: to, cc, bcc
initialMessage.body
object
wymagane
Pokaż parametry podrzędne
initialMessage.body.text
object
wymagane
Pokaż parametry podrzędne
initialMessage.body.text.actions
array of object
Pokaż parametry podrzędne
initialMessage.body.text.actions.link
object
wymagane
Pokaż parametry podrzędne
initialMessage.body.text.actions.link.metadata
object
Pokaż parametry podrzędne
initialMessage.body.text.actions.link.metadata.description
object
Pokaż parametry podrzędne
initialMessage.body.text.actions.link.metadata.description.label
string
wymagane
initialMessage.body.text.actions.link.text
string
wymagane
initialMessage.body.text.actions.link.url
string
wymagane
initialMessage.body.text.actions.type
string
wymagane
Possible values: link
initialMessage.body.text.attachments
array of object
Pokaż parametry podrzędne
initialMessage.body.text.attachments.content
string
initialMessage.body.text.attachments.contentId
string
initialMessage.body.text.attachments.contentType
string
initialMessage.body.text.attachments.filename
string
wymagane
initialMessage.body.text.attachments.inline
boolean
initialMessage.body.text.attachments.mediaUrl
string
wymagane
initialMessage.body.text.metadata
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.apple
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.apple.appClipPreview
boolean
initialMessage.body.text.metadata.apple.appClipRegion
string
initialMessage.body.text.metadata.apple.summaryText
string
initialMessage.body.text.metadata.headers
object
initialMessage.body.text.metadata.line
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.line.emoji
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.line.emoji.items
array of object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.line.emoji.items.emojiId
string
wymagane
initialMessage.body.text.metadata.line.emoji.items.index
integer
wymagane
initialMessage.body.text.metadata.line.emoji.items.length
integer
initialMessage.body.text.metadata.line.emoji.items.productId
string
wymagane
initialMessage.body.text.metadata.paymentDetails
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.paymentDetails.amount
string
wymagane
initialMessage.body.text.metadata.paymentDetails.currency
string
wymagane
initialMessage.body.text.metadata.paymentDetails.sessionIdentifier
string
initialMessage.body.text.metadata.paymentDetails.state
string
wymagane
initialMessage.body.text.metadata.subject
string
initialMessage.body.text.metadata.telegram
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.telegram.parseMode
string
initialMessage.body.text.metadata.whatsapp
object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.whatsapp.callPermissionExpiration
string
initialMessage.body.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
initialMessage.body.text.metadata.whatsapp.previewUrl
boolean
wymagane
initialMessage.body.text.metadata.whatsapp.sharedContacts
array of object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.whatsapp.sharedContacts.origin
string
wymagane
initialMessage.body.text.metadata.whatsapp.sharedContacts.phones
array of object
Pokaż parametry podrzędne
initialMessage.body.text.metadata.whatsapp.sharedContacts.phones.phone
string
wymagane
initialMessage.body.text.metadata.whatsapp.sharedContacts.phones.type
string
wymagane
initialMessage.body.text.metadata.whatsapp.sharedContacts.phones.waId
string
wymagane
initialMessage.body.text.metadata.whatsapp.sharedContacts.vcard
string
initialMessage.body.text.text
string
wymagane
initialMessage.body.type
string
wymagane
Possible values: text
initialMessage.draft
boolean
Whether this message is a draft.
attributes
object
A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.
Treść odpowiedzi
accessibility
string
wymagane
Possible values: open, invite-only, request-to-join, private
activeParticipantCount
integer
wymagane
assigneeId
string
attributes
object
category
string
channelId
string
wymagane
createdAt
string
wymagane
description
string
directory
string
featuredParticipants
array of object
wymagane
Pokaż atrybuty podrzędne
featuredParticipants.avatarUrl
string
featuredParticipants.contact
object
Pokaż atrybuty podrzędne
featuredParticipants.contact.identifierKey
string
wymagane
featuredParticipants.contact.identifierValue
string
wymagane
featuredParticipants.contact.platformAddress
string
featuredParticipants.contact.platformAddressSelector
string
featuredParticipants.conversationId
string
featuredParticipants.createdAt
string
featuredParticipants.displayName
string
featuredParticipants.id
string
wymagane
featuredParticipants.resourceUri
string
featuredParticipants.status
string
Possible values: invited, pending, active, inactive
featuredParticipants.type
string
wymagane
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
featuredParticipants.updatedAt
string
hasDraft
boolean
id
string
wymagane
inbox
object
Pokaż atrybuty podrzędne
inbox.id
string
wymagane
inbox.identifier
string
wymagane
inbox.ownerId
string
wymagane
inbox.ownerType
string
wymagane
Possible values: user, group
inbox.type
string
wymagane
Possible values: personal, shared, support
initiatingParticipant
object
Pokaż atrybuty podrzędne
initiatingParticipant.avatarUrl
string
initiatingParticipant.contact
object
Pokaż atrybuty podrzędne
initiatingParticipant.contact.identifierKey
string
wymagane
initiatingParticipant.contact.identifierValue
string
wymagane
initiatingParticipant.contact.platformAddress
string
initiatingParticipant.contact.platformAddressSelector
string
initiatingParticipant.conversationId
string
initiatingParticipant.createdAt
string
initiatingParticipant.displayName
string
initiatingParticipant.id
string
wymagane
initiatingParticipant.resourceUri
string
initiatingParticipant.status
string
Possible values: invited, pending, active, inactive
initiatingParticipant.type
string
wymagane
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
initiatingParticipant.updatedAt
string
lastMessage
object
Pokaż atrybuty podrzędne
lastMessage.createdAt
string
wymagane
lastMessage.draft
boolean
wymagane
lastMessage.id
string
wymagane
lastMessage.preview
object
wymagane
Pokaż atrybuty podrzędne
lastMessage.preview.text
string
lastMessage.recipients
array of object
Pokaż atrybuty podrzędne
lastMessage.recipients.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Pokaż atrybuty podrzędne
lastMessage.recipients.contactAnnotation.name
string
lastMessage.recipients.countryCode
string
lastMessage.recipients.id
string
The ID of the contact.
lastMessage.recipients.identifierKey
string
The identifier key for finding the contact (e.g. emailaddress, phonenumber). For WhatsApp channels with BSUID support, use whatsappbsuid to send to a contact by their Business-Scoped User ID.
lastMessage.recipients.identifierValue
string
The identifier value for finding the contact.
lastMessage.recipients.identifiers
array of object
Additional identifiers to augment the contact during resolution.
Pokaż atrybuty podrzędne
lastMessage.recipients.identifiers.identifierKey
string
wymagane
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
lastMessage.recipients.identifiers.identifierValue
string
wymagane
The identifier value for finding the contact.
lastMessage.recipients.platformAddress
string
The resolved platform address used to deliver the message (e.g. phone number or email address).
lastMessage.recipients.platformAddressSelector
string
An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.
lastMessage.recipients.receiverExpression
string
lastMessage.recipients.receiverValue
string
lastMessage.recipients.type
string
The type of the receiver (e.g. to, cc, bcc for email).
lastMessage.sender
object
Pokaż atrybuty podrzędne
lastMessage.sender.email
string
lastMessage.sender.name
string
lastMessage.sender.avatarUrl
string
lastMessage.sender.contact
object
Pokaż atrybuty podrzędne
lastMessage.sender.contact.identifierKey
string
wymagane
lastMessage.sender.contact.identifierValue
string
wymagane
lastMessage.sender.contact.platformAddress
string
lastMessage.sender.contact.platformAddressSelector
string
lastMessage.sender.conversationId
string
lastMessage.sender.createdAt
string
lastMessage.sender.displayName
string
lastMessage.sender.id
string
wymagane
lastMessage.sender.resourceUri
string
lastMessage.sender.status
string
Possible values: invited, pending, active, inactive
lastMessage.sender.type
string
wymagane
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
lastMessage.sender.updatedAt
string
lastMessage.status
string
wymagane
Possible values: accepted, processing, sent, sending_failed, delivered, delivery_failed, deleted
lastMessage.type
string
wymagane
Possible values: text, html, image, file, gif, location, carousel, list, section, authentication, action, comment
lastMessageIncomingAt
string
lastMessageOutgoingAt
string
name
string
wymagane
participants
array of object
Pokaż atrybuty podrzędne
participants.contact
object
Pokaż atrybuty podrzędne
participants.contact.identifierKey
string
wymagane
participants.contact.identifierValue
string
wymagane
participants.contact.platformAddress
string
participants.contact.platformAddressSelector
string
participants.id
string
wymagane
participants.type
string
wymagane
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
pendingParticipantCount
integer
platformStyle
string
wymagane
Possible values: direct, email, direct-multiple, direct-threaded, group-multiple
privateAttributes
string
read
boolean
referral
object
Pokaż atrybuty podrzędne
referral.caption
string
referral.mediaType
string
referral.mediaUrl
string
referral.sourceId
string
wymagane
referral.sourceType
string
referral.sourceUrl
string
referral.text
string
referral.timestamp
string
referral.title
string
referral.username
string
resource
object
Pokaż atrybuty podrzędne
resource.id
string
wymagane
resource.type
string
wymagane
Possible values: task, task-conversation, reimbursement, sales-lead, sales-opportunity, sales-account, expense, project
resourceUri
string
starred
boolean
status
string
wymagane
Possible values: deleted, active, closed, spam, archived
style
string
wymagane
Possible values: default, directMessage, chatChannel, personalInbox, resource, groupInbox, support
summary
string
tags
array of string
updatedAt
string
wymagane
visibility
string
wymagane
Possible values: public, private, direct, group
Przykład kodu
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/conversations' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Examples

Starting a conversation with a simple message

Przykład kodu
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"
  }
}'

Starting a conversation with an email template message

Przykład kodu
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"
  }
}'

Starting a conversation with a WhatsApp template message

Przykład kodu
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"
  }
}'