DocumentationEngagement Platform API
Sign inGet started
Guides
API

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 typeDescriptionMeaning of participant ID
accessKeyA Bird API access key. This is what you'll commonly use when sending messages through the Conversations APIAccess key ID
contactA Bird contactContact ID
flowA Bird flowFlow ID
POST
/workspaces/{workspaceId}/conversations/{conversationId}/messages
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.
Paramètres de chemin
conversationId
string
The conversation ID
Corps de la requête
A message specifying its contents through a body field.
draft
boolean
Whether this message is a draft.
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.
sender
object
Message sender information for email.
Afficher les paramètres enfants
sender.name
string
obligatoire
Sender name shown in the email "From" header.
sender.email
string
Sender email address.
sender.emailReplyToAddress
string
Sender email address to reply to.
participantId
string
obligatoire
Participant ID.
replyToMessageId
string
Message ID to reply to. Only used for email channels, other channel types must use replyTo.
participantType
string
obligatoire
Participant type. When sending messages through the Conversations API, the participant be one of accessKey, flow, or contact.
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
participantContactIdentifierKey
string
The key of the contact identifier to use for the participant. This is used when the participant is not a user in the system.
participantContactIdentifierValue
string
recipients
array of object
List of recipients.
Afficher les paramètres enfants
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.
recipients.identifierKey
string
Identifier key of the contact depending on which channel is being used.
recipients.identifierValue
string
obligatoire
Identifier of the contact, such as a phone number or email address.
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.
recipients.type
string
obligatoire
Whether the email address is in the email's "To", "CC", or "BCC" headers.
Possible values: to, cc, bcc
addMissingParticipants
boolean
If enabled, conveniently adds missing participants to the conversation without requiring additional API calls to /participants. It's recommended to set this to true.
body
object
obligatoire
Afficher les paramètres enfants
body.text
object
obligatoire
Afficher les paramètres enfants
body.text.actions
array of object
Afficher les paramètres enfants
body.text.actions.link
object
obligatoire
Afficher les paramètres enfants
body.text.actions.link.metadata
object
Afficher les paramètres enfants
body.text.actions.link.metadata.description
object
Afficher les paramètres enfants
body.text.actions.link.metadata.description.label
string
obligatoire
body.text.actions.link.text
string
obligatoire
body.text.actions.link.url
string
obligatoire
body.text.actions.type
string
obligatoire
Possible values: link
body.text.attachments
array of object
Afficher les paramètres enfants
body.text.attachments.content
string
body.text.attachments.contentId
string
body.text.attachments.contentType
string
body.text.attachments.filename
string
obligatoire
body.text.attachments.inline
boolean
body.text.attachments.mediaUrl
string
obligatoire
body.text.metadata
object
Afficher les paramètres enfants
body.text.metadata.apple
object
Afficher les paramètres enfants
body.text.metadata.apple.appClipPreview
boolean
body.text.metadata.apple.appClipRegion
string
body.text.metadata.apple.summaryText
string
body.text.metadata.headers
object
body.text.metadata.line
object
Afficher les paramètres enfants
body.text.metadata.line.emoji
object
Afficher les paramètres enfants
body.text.metadata.line.emoji.items
array of object
Afficher les paramètres enfants
body.text.metadata.line.emoji.items.emojiId
string
obligatoire
body.text.metadata.line.emoji.items.index
integer
obligatoire
body.text.metadata.line.emoji.items.length
integer
body.text.metadata.line.emoji.items.productId
string
obligatoire
body.text.metadata.paymentDetails
object
Afficher les paramètres enfants
body.text.metadata.paymentDetails.amount
string
obligatoire
body.text.metadata.paymentDetails.currency
string
obligatoire
body.text.metadata.paymentDetails.sessionIdentifier
string
body.text.metadata.paymentDetails.state
string
obligatoire
body.text.metadata.subject
string
body.text.metadata.telegram
object
Afficher les paramètres enfants
body.text.metadata.telegram.parseMode
string
body.text.metadata.whatsapp
object
Afficher les paramètres enfants
body.text.metadata.whatsapp.callPermissionExpiration
string
body.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
body.text.metadata.whatsapp.previewUrl
boolean
obligatoire
body.text.metadata.whatsapp.sharedContacts
array of object
Afficher les paramètres enfants
body.text.metadata.whatsapp.sharedContacts.origin
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones
array of object
Afficher les paramètres enfants
body.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.vcard
string
body.text.text
string
obligatoire
body.type
string
obligatoire
Possible values: text
replyTo
object
Afficher les paramètres enfants
replyTo.id
string
The ID of the message that is being replied to.
replyTo.order
integer
The order of the message part in the conversation.
replyTo.platformReference
string
replyTo.type
string
Possible values: message, click
appendPreviousMessage
boolean
channelId
string
Channel ID.
participants
array of object
When creating a new conversation, this is the list of participants.
Afficher les paramètres enfants
Create a participant of the type user, access key, flow, agent, bot, or action rule.
participants.id
string
obligatoire
The ID of the user, access key, flow, agent, bot, or action rule.
participants.type
string
obligatoire
Participant type.
Possible values: user, accessKey, flow, agent, bot, collaborationAutomation
name
string
When creating a new conversation, this is the subject of the email.
description
string
When creating a new conversation, this is the description associated with it.
visibility
string
Possible values: public, private, direct, group
accessibility
string
Possible values: open, invite-only, request-to-join, private
attributes
object
A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.
meta
object
Message metadata fields that might be populated depending on the channel being used.
Afficher les paramètres enfants
meta.email
object
Metadata fields for email messages.
Afficher les paramètres enfants
meta.email.subject
string
Email subject line.
meta.email.headers
object
Additional email headers.
meta.email.from
object
Email From address.
Afficher les paramètres enfants
meta.email.from.username
string
The username part of the adress, e.g. for the address john.doe@bird.com, this value will be john.doe.
meta.email.from.displayName
string
The display name of an email participant.
meta.extraInformation
object
A free-form object that might contain additional metadata fields. Messages sent through the Conversations API are automatically classified with the conversation useCase, so on Meta channels (Messenger, Instagram) they are delivered with Meta's HUMAN_AGENT tag (the 7-day human-agent window).
meta.referral
object
This represents a social media post or an ad that was referenced when starting the conversation.
Afficher les paramètres enfants
meta.referral.source
string
meta.referral.title
string
meta.referral.text
string
meta.referral.group
string
meta.referral.metadata
object
Afficher les paramètres enfants
meta.referral.metadata.sourceId
string
The ID of the social media post or ad.
meta.referral.metadata.sourceUrl
string
The URL of the social media post or ad.
meta.referral.metadata.mediaType
string
Type of media used in the post or ad.
meta.referral.metadata.mediaUrl
string
Link to the media associated with the referral post or ad.
meta.referral.metadata.caption
string
Caption associated with the referral post or ad.
meta.referral.metadata.username
string
Username who created the referral post or ad.
meta.referral.metadata.timestamp
string
Timestamp when the referral post or ad was created.
meta.referral.metadata.trackingId
string
Corps de la réponse
body
object
Afficher les attributs enfants
body.text
object
obligatoire
Afficher les attributs enfants
body.text.actions
array of object
Afficher les attributs enfants
body.text.actions.link
object
obligatoire
Afficher les attributs enfants
body.text.actions.link.metadata
object
Afficher les attributs enfants
body.text.actions.link.metadata.description
object
Afficher les attributs enfants
body.text.actions.link.metadata.description.label
string
obligatoire
body.text.actions.link.text
string
obligatoire
body.text.actions.link.url
string
obligatoire
body.text.actions.type
string
obligatoire
Possible values: link
body.text.attachments
array of object
Afficher les attributs enfants
body.text.attachments.content
string
body.text.attachments.contentId
string
body.text.attachments.contentType
string
body.text.attachments.filename
string
obligatoire
body.text.attachments.inline
boolean
body.text.attachments.mediaUrl
string
obligatoire
body.text.metadata
object
Afficher les attributs enfants
body.text.metadata.apple
object
Afficher les attributs enfants
body.text.metadata.apple.appClipPreview
boolean
body.text.metadata.apple.appClipRegion
string
body.text.metadata.apple.summaryText
string
body.text.metadata.headers
object
body.text.metadata.line
object
Afficher les attributs enfants
body.text.metadata.line.emoji
object
Afficher les attributs enfants
body.text.metadata.line.emoji.items
array of object
Afficher les attributs enfants
body.text.metadata.line.emoji.items.emojiId
string
obligatoire
body.text.metadata.line.emoji.items.index
integer
obligatoire
body.text.metadata.line.emoji.items.length
integer
body.text.metadata.line.emoji.items.productId
string
obligatoire
body.text.metadata.paymentDetails
object
Afficher les attributs enfants
body.text.metadata.paymentDetails.amount
string
obligatoire
body.text.metadata.paymentDetails.currency
string
obligatoire
body.text.metadata.paymentDetails.sessionIdentifier
string
body.text.metadata.paymentDetails.state
string
obligatoire
body.text.metadata.subject
string
body.text.metadata.telegram
object
Afficher les attributs enfants
body.text.metadata.telegram.parseMode
string
body.text.metadata.whatsapp
object
Afficher les attributs enfants
body.text.metadata.whatsapp.callPermissionExpiration
string
body.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
body.text.metadata.whatsapp.previewUrl
boolean
obligatoire
body.text.metadata.whatsapp.sharedContacts
array of object
Afficher les attributs enfants
body.text.metadata.whatsapp.sharedContacts.origin
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones
array of object
Afficher les attributs enfants
body.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatoire
body.text.metadata.whatsapp.sharedContacts.vcard
string
body.text.text
string
obligatoire
body.type
string
obligatoire
Possible values: text
channelId
string
conversationCreatedAt
string
conversationId
string
obligatoire
createdAt
string
obligatoire
draft
boolean
obligatoire
Whether this message is a draft.
draftMeta
object
Metadata for draft messages.
Afficher les attributs enfants
draftMeta.creatorType
string
obligatoire
Possible values: user, bot
id
string
obligatoire
A unique identifier for this message.
interactions
array of object
A list of interactions associated with the message (e.g. read receipts, clicks, reactions).
Afficher les attributs enfants
interactions.bodyTemplateProjectId
string
interactions.channelId
string
obligatoire
interactions.context
object
obligatoire
Afficher les attributs enfants
interactions.context.id
string
interactions.context.tagIds
array of string
interactions.context.type
string
interactions.createdAt
string
obligatoire
interactions.details
string
interactions.id
string
obligatoire
interactions.isFirstInteraction
boolean
interactions.isFirstInteractionIncludingBots
boolean
interactions.journey
object
Afficher les attributs enfants
interactions.journey.id
string
interactions.journey.name
string
interactions.journey.runId
string
interactions.journey.scheduleExecutionId
string
interactions.journey.stepId
string
interactions.messageCreatedAt
string
interactions.messageId
string
obligatoire
interactions.messagePartsCount
integer
obligatoire
interactions.messageReference
string
obligatoire
interactions.messageTags
array of string
interactions.metadata
object
Afficher les attributs enfants
interactions.metadata.button
object
Afficher les attributs enfants
interactions.metadata.button.payload
string
obligatoire
interactions.metadata.conversion
object
Afficher les attributs enfants
interactions.metadata.conversion.method
string
Method of entering the code
Possible values: unknown, manual, auto
interactions.metadata.conversion.status
string
Status of the conversion
Possible values: converted, canceled, not_converted, incorrect_code, resent, received_after_expiration
interactions.metadata.conversion.timestamp
string
Timestamp of when the conversion was recorded
interactions.metadata.conversion.type
string
Type of conversion
Possible values: otp, url, promo_code
interactions.metadata.extraInformation
object
interactions.metadata.link
object
Afficher les attributs enfants
interactions.metadata.link.clickType
string
Possible values: link, button
interactions.metadata.link.name
string
obligatoire
interactions.metadata.link.url
string
obligatoire
interactions.metadata.prefetched
boolean
interactions.metadata.reaction
object
Afficher les attributs enfants
interactions.metadata.reaction.action
string
obligatoire
Possible values: react, unreact
interactions.metadata.reaction.emoji
string
obligatoire
interactions.metadata.renderedContentBlocks
array of string
interactions.metadata.subscriptionList
object
Afficher les attributs enfants
interactions.metadata.subscriptionList.subscriptionListId
string
obligatoire
interactions.notification
object
Afficher les attributs enfants
interactions.notification.template
string
interactions.notification.url
string
obligatoire
interactions.platformId
string
obligatoire
interactions.platformReferenceId
string
interactions.receiver
object
obligatoire
Afficher les attributs enfants
interactions.receiver.connector
object
Afficher les attributs enfants
interactions.receiver.connector.annotations
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Afficher les attributs enfants
interactions.receiver.connector.annotations.name
string
interactions.receiver.connector.id
string
obligatoire
interactions.receiver.connector.identifierValue
string
The identifier value of the sender or receiver connector (e.g. email address or phone number).
interactions.receiver.connector.types
array of string
interactions.receiver.contacts
array of object
Afficher les attributs enfants
interactions.receiver.contacts.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Afficher les attributs enfants
interactions.receiver.contacts.contactAnnotation.name
string
interactions.receiver.contacts.countryCode
string
interactions.receiver.contacts.id
string
The ID of the contact.
interactions.receiver.contacts.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.
interactions.receiver.contacts.identifierValue
string
The identifier value for finding the contact.
interactions.receiver.contacts.identifiers
array of object
Additional identifiers to augment the contact during resolution.
Afficher les attributs enfants
interactions.receiver.contacts.identifiers.identifierKey
string
obligatoire
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
interactions.receiver.contacts.identifiers.identifierValue
string
obligatoire
The identifier value for finding the contact.
interactions.receiver.contacts.platformAddress
string
The resolved platform address used to deliver the message (e.g. phone number or email address).
interactions.receiver.contacts.platformAddressSelector
string
An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.
interactions.receiver.contacts.receiverExpression
string
interactions.receiver.contacts.receiverValue
string
interactions.receiver.contacts.type
string
The type of the receiver (e.g. to, cc, bcc for email).
interactions.receiver.device
object
Afficher les attributs enfants
interactions.receiver.device.gateway
string
obligatoire
Possible values: firebase, apns, web
interactions.receiver.device.id
string
obligatoire
interactions.receiver.device.identifierValue
string
obligatoire
interactions.receiver.inbox
object
Afficher les attributs enfants
interactions.receiver.inbox.emailRecipientType
string
interactions.receiver.inbox.id
string
obligatoire
interactions.receiver.inbox.identifierKey
string
obligatoire
interactions.receiver.inbox.identifierValue
string
obligatoire
interactions.receiver.inbox.type
string
obligatoire
Possible values: user, group
interactions.receiver.userContacts
array of object
Afficher les attributs enfants
interactions.receiver.userContacts.id
string
obligatoire
interactions.receiver.userContacts.identifierKey
string
obligatoire
interactions.receiver.userContacts.identifierValue
string
obligatoire
interactions.receiver.userContacts.type
string
interactions.type
string
obligatoire
Possible values: invalid, read, opened, clicked, reported-as-spam, unsubscribe-request, delete, reaction, subscribe-request, subscribe-consent, conversion
interactions.useCaseType
string
Possible values: unspecified, marketing, otp, transactional, conversation, test
meta
object
Afficher les attributs enfants
meta.campaign
object
Afficher les attributs enfants
meta.campaign.id
string
meta.campaign.name
string
meta.campaignId
string
meta.chargeOnceDelivered
boolean
meta.email
object
Afficher les attributs enfants
meta.email.from
object
Afficher les attributs enfants
meta.email.from.displayName
string
meta.email.from.username
string
meta.email.headers
object
meta.email.subject
string
meta.extraInformation
object
meta.flow
object
Afficher les attributs enfants
meta.flow.id
string
meta.flow.name
string
meta.flow.runId
string
meta.flow.scheduleExecutionId
string
meta.flow.stepId
string
meta.formResponse
object
Afficher les attributs enfants
meta.formResponse.id
string
obligatoire
meta.formResponse.jsonResponse
string
obligatoire
meta.formResponse.requestIdentifier
string
obligatoire
meta.formResponse.selections
array of object
Afficher les attributs enfants
meta.formResponse.selections.items
array of object
Afficher les attributs enfants
meta.formResponse.selections.items.identifier
string
obligatoire
meta.formResponse.selections.items.title
string
obligatoire
meta.formResponse.selections.items.type
string
obligatoire
meta.formResponse.selections.items.value
string
obligatoire
meta.formResponse.selections.pageIdentifier
string
obligatoire
meta.formResponse.selections.subtitle
string
obligatoire
meta.formResponse.selections.title
string
obligatoire
meta.formResponse.sessionIdentifier
string
obligatoire
meta.formResponse.template
string
obligatoire
meta.formResponse.version
string
obligatoire
meta.ignoreGlobalHoldout
boolean
meta.ignoreQuietHours
boolean
meta.journey
object
Afficher les attributs enfants
meta.journey.id
string
meta.journey.name
string
meta.journey.runId
string
meta.journey.scheduleExecutionId
string
meta.journey.stepId
string
meta.longToShortLinks
object
meta.metaThreadId
string
meta.navigatorId
string
meta.navigatorMessageId
string
meta.order
object
The order object contains information about the purchase order associated with the message.
Afficher les attributs enfants
meta.order.products
array of object
Afficher les attributs enfants
meta.order.products.externalCatalogId
string
The platform-specific catalog ID of the product.
meta.order.products.externalProductId
string
obligatoire
The platform-specific product ID.
meta.order.products.price
object
obligatoire
Afficher les attributs enfants
meta.order.products.price.amount
integer
obligatoire
meta.order.products.price.currencyCode
string
obligatoire
meta.order.products.price.exponent
integer
obligatoire
meta.order.products.quantity
integer
obligatoire
The number of items purchased.
meta.pushNotifications
object
Afficher les attributs enfants
meta.pushNotifications.gatewayTypeOverride
string
Possible values: firebase, apns, web
meta.referral
object
Afficher les attributs enfants
meta.referral.group
string
meta.referral.metadata
object
Afficher les attributs enfants
meta.referral.metadata.caption
string
meta.referral.metadata.mediaType
string
meta.referral.metadata.mediaUrl
string
meta.referral.metadata.sourceId
string
obligatoire
meta.referral.metadata.sourceUrl
string
meta.referral.metadata.timestamp
string
meta.referral.metadata.trackingId
string
meta.referral.metadata.username
string
meta.referral.source
string
obligatoire
meta.referral.text
string
meta.referral.title
string
meta.referredProduct
object
Referred product in an incoming message (e.g. a product shared in a WhatsApp catalog message).
Afficher les attributs enfants
meta.referredProduct.externalCatalogId
string
The platform-specific catalog ID of the product.
meta.referredProduct.externalProductId
string
obligatoire
The platform-specific product ID.
meta.renderedContentBlocks
array of string
meta.shortToLongLinks
object
meta.skipThisMessage
string
Possible values: campaignHoldout, globalHoldout, journeyHoldout
meta.sms
object
Afficher les attributs enfants
meta.sms.gatewayId
integer
meta.sms.registeredDelivery
string
Possible values: final, intermediate, all, noDlr
meta.sms.smartEncoding
boolean
When enabled, attempts to transliterate Unicode characters to GSM-7 equivalents. If the resulting text is fully GSM-7 compatible, fewer message segments may be required. The original message body is preserved; transliteration is only applied when sending.
meta.sms.smpp
object
Afficher les attributs enfants
meta.sms.smpp.segments
array of object
Afficher les attributs enfants
meta.sms.smpp.segments.id
string
obligatoire
meta.sms.smpp.segments.registeredDelivery
string
obligatoire
Possible values: final, intermediate, all, noDlr
meta.sms.smpp.userId
string
obligatoire
meta.sms.validity
string
meta.useFallback
boolean
reason
string
Failure reason. Populated when status is sending_failed or delivery_failed.
receiver
object
Afficher les attributs enfants
receiver.connector
object
Afficher les attributs enfants
receiver.connector.annotations
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Afficher les attributs enfants
receiver.connector.annotations.name
string
receiver.connector.id
string
obligatoire
receiver.connector.identifierValue
string
The identifier value of the sender or receiver connector (e.g. email address or phone number).
receiver.connector.types
array of string
receiver.contacts
array of object
Afficher les attributs enfants
receiver.contacts.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Afficher les attributs enfants
receiver.contacts.contactAnnotation.name
string
receiver.contacts.countryCode
string
receiver.contacts.id
string
The ID of the contact.
receiver.contacts.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.
receiver.contacts.identifierValue
string
The identifier value for finding the contact.
receiver.contacts.identifiers
array of object
Additional identifiers to augment the contact during resolution.
Afficher les attributs enfants
receiver.contacts.identifiers.identifierKey
string
obligatoire
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
receiver.contacts.identifiers.identifierValue
string
obligatoire
The identifier value for finding the contact.
receiver.contacts.platformAddress
string
The resolved platform address used to deliver the message (e.g. phone number or email address).
receiver.contacts.platformAddressSelector
string
An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.
receiver.contacts.receiverExpression
string
receiver.contacts.receiverValue
string
receiver.contacts.type
string
The type of the receiver (e.g. to, cc, bcc for email).
receiver.device
object
Afficher les attributs enfants
receiver.device.gateway
string
obligatoire
Possible values: firebase, apns, web
receiver.device.id
string
obligatoire
receiver.device.identifierValue
string
obligatoire
receiver.inbox
object
Afficher les attributs enfants
receiver.inbox.emailRecipientType
string
receiver.inbox.id
string
obligatoire
receiver.inbox.identifierKey
string
obligatoire
receiver.inbox.identifierValue
string
obligatoire
receiver.inbox.type
string
obligatoire
Possible values: user, group
receiver.userContacts
array of object
Afficher les attributs enfants
receiver.userContacts.id
string
obligatoire
receiver.userContacts.identifierKey
string
obligatoire
receiver.userContacts.identifierValue
string
obligatoire
receiver.userContacts.type
string
receiverTypes
array of string
Receiver types for the message (to/cc/bcc). Currently only used for inbound email messages.
recipients
array of object
Afficher les attributs enfants
recipients.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Afficher les attributs enfants
recipients.contactAnnotation.name
string
recipients.countryCode
string
recipients.id
string
The ID of the contact.
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.
recipients.identifierValue
string
The identifier value for finding the contact.
recipients.identifiers
array of object
Additional identifiers to augment the contact during resolution.
Afficher les attributs enfants
recipients.identifiers.identifierKey
string
obligatoire
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
recipients.identifiers.identifierValue
string
obligatoire
The identifier value for finding the contact.
recipients.platformAddress
string
The resolved platform address used to deliver the message (e.g. phone number or email address).
recipients.platformAddressSelector
string
An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.
recipients.receiverExpression
string
recipients.receiverValue
string
recipients.type
string
The type of the receiver (e.g. to, cc, bcc for email).
reference
string
obligatoire
A customizable ID assigned to messages you send. Can be used to correlate messages with data from your own services. Must be globally unique within a workspace.
replyTo
object
Afficher les attributs enfants
replyTo.id
string
The ID of the message that is being replied to.
replyTo.order
integer
The order of the message part in the conversation.
replyTo.platformReference
string
replyTo.type
string
Possible values: message, click
resourceUri
string
sender
object
obligatoire
Afficher les attributs enfants
sender.email
string
sender.name
string
sender.avatarUrl
string
sender.contact
object
Afficher les attributs enfants
sender.contact.identifierKey
string
obligatoire
sender.contact.identifierValue
string
obligatoire
sender.contact.platformAddress
string
sender.contact.platformAddressSelector
string
sender.conversationId
string
sender.createdAt
string
sender.displayName
string
sender.id
string
obligatoire
sender.resourceUri
string
sender.status
string
Possible values: invited, pending, active, inactive
sender.type
string
obligatoire
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
sender.updatedAt
string
source
string
obligatoire
Possible values: conversations, channels, bots, external
status
string
obligatoire
Possible values: accepted, processing, sent, sending_failed, delivered, delivery_failed, deleted
template
object
Afficher les attributs enfants
template.attachments
array of object
Afficher les attributs enfants
template.attachments.content
string
template.attachments.contentType
string
template.attachments.filename
string
obligatoire
template.attachments.inline
boolean
obligatoire
template.attachments.mediaUrl
string
obligatoire
template.deployment
object
template.locale
string
obligatoire
template.name
string
The platform name of the template.
template.parameters
array of object
Afficher les attributs enfants
template.parameters.key
string
obligatoire
template.parameters.sourceUrl
object
Afficher les attributs enfants
template.parameters.sourceUrl.fullyReplaced
boolean
obligatoire
template.parameters.sourceUrl.value
string
obligatoire
template.parameters.type
string
obligatoire
Possible values: string, timeslotList, productSections, productList, number, boolean, sectionList, shippingMethodList, lineItemList, whatsappProductSections, whatsappProductItems, shortLink, object, carouselCards, appleFormPageItems
template.parameters.value
object or array or string or number or boolean
obligatoire
template.projectId
string
obligatoire
The ID of the project from Studio.
template.settings
object
Afficher les attributs enfants
template.settings.disallowMmLite
boolean
template.shortLinks
object
Afficher les attributs enfants
template.shortLinks.domain
string
obligatoire
The domain to use when shortening links. When set to default, uses the default link shortening domain for the workspace.
template.shortLinks.enabled
boolean
obligatoire
Enables link shortening for SMS messages.
template.templateBody
object
Afficher les attributs enfants
template.templateBody.text
object
obligatoire
Afficher les attributs enfants
template.templateBody.text.actions
array of object
Afficher les attributs enfants
template.templateBody.text.actions.link
object
obligatoire
Afficher les attributs enfants
template.templateBody.text.actions.link.metadata
object
Afficher les attributs enfants
template.templateBody.text.actions.link.metadata.description
object
Afficher les attributs enfants
template.templateBody.text.actions.link.metadata.description.label
string
obligatoire
template.templateBody.text.actions.link.text
string
obligatoire
template.templateBody.text.actions.link.url
string
obligatoire
template.templateBody.text.actions.type
string
obligatoire
Possible values: link
template.templateBody.text.attachments
array of object
Afficher les attributs enfants
template.templateBody.text.attachments.content
string
template.templateBody.text.attachments.contentId
string
template.templateBody.text.attachments.contentType
string
template.templateBody.text.attachments.filename
string
obligatoire
template.templateBody.text.attachments.inline
boolean
template.templateBody.text.attachments.mediaUrl
string
obligatoire
template.templateBody.text.metadata
object
Afficher les attributs enfants
template.templateBody.text.metadata.apple
object
Afficher les attributs enfants
template.templateBody.text.metadata.apple.appClipPreview
boolean
template.templateBody.text.metadata.apple.appClipRegion
string
template.templateBody.text.metadata.apple.summaryText
string
template.templateBody.text.metadata.headers
object
template.templateBody.text.metadata.line
object
Afficher les attributs enfants
template.templateBody.text.metadata.line.emoji
object
Afficher les attributs enfants
template.templateBody.text.metadata.line.emoji.items
array of object
Afficher les attributs enfants
template.templateBody.text.metadata.line.emoji.items.emojiId
string
obligatoire
template.templateBody.text.metadata.line.emoji.items.index
integer
obligatoire
template.templateBody.text.metadata.line.emoji.items.length
integer
template.templateBody.text.metadata.line.emoji.items.productId
string
obligatoire
template.templateBody.text.metadata.paymentDetails
object
Afficher les attributs enfants
template.templateBody.text.metadata.paymentDetails.amount
string
obligatoire
template.templateBody.text.metadata.paymentDetails.currency
string
obligatoire
template.templateBody.text.metadata.paymentDetails.sessionIdentifier
string
template.templateBody.text.metadata.paymentDetails.state
string
obligatoire
template.templateBody.text.metadata.subject
string
template.templateBody.text.metadata.telegram
object
Afficher les attributs enfants
template.templateBody.text.metadata.telegram.parseMode
string
template.templateBody.text.metadata.whatsapp
object
Afficher les attributs enfants
template.templateBody.text.metadata.whatsapp.callPermissionExpiration
string
template.templateBody.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
template.templateBody.text.metadata.whatsapp.previewUrl
boolean
obligatoire
template.templateBody.text.metadata.whatsapp.sharedContacts
array of object
Afficher les attributs enfants
template.templateBody.text.metadata.whatsapp.sharedContacts.origin
string
obligatoire
template.templateBody.text.metadata.whatsapp.sharedContacts.phones
array of object
Afficher les attributs enfants
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatoire
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatoire
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatoire
template.templateBody.text.metadata.whatsapp.sharedContacts.vcard
string
template.templateBody.text.text
string
obligatoire
template.templateBody.type
string
obligatoire
Possible values: text
template.utmParameters
array of object
Afficher les attributs enfants
template.utmParameters.key
string
obligatoire
template.utmParameters.value
string
obligatoire
template.variables
object
template.version
string
obligatoire
The version of the template.
type
string
Possible values: text, html, image, file, gif, location, carousel, list, section, authentication, action
updatedAt
string
obligatoire
Exemple de code
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Examples

Sending a simple message

Exemple de code
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": "some.customer@example.com"
    }
  ],
  "body": {
    "type": "text",
    "text": {
      "text": "Hey, listen!"
    }
  }
}'

Sending a template message

Exemple de code
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": "68b80b8d-8060-42df-bda3-73505a8fdb84",
  "recipients": [
    {
      "identifierKey": "emailaddress",
      "identifierValue": "john.doe@bird.com",
      "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
}'