DocumentaciónEngagement 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.
Parámetros de ruta
conversationId
string
The conversation ID
Cuerpo de la solicitud
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.
Mostrar parámetros secundarios
sender.name
string
obligatorio
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
obligatorio
Participant ID.
replyToMessageId
string
Message ID to reply to. Only used for email channels, other channel types must use replyTo.
participantType
string
obligatorio
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.
Mostrar parámetros secundarios
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
obligatorio
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
obligatorio
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
obligatorio
Mostrar parámetros secundarios
body.text
object
obligatorio
Mostrar parámetros secundarios
body.text.actions
array of object
Mostrar parámetros secundarios
body.text.actions.link
object
obligatorio
Mostrar parámetros secundarios
body.text.actions.link.metadata
object
Mostrar parámetros secundarios
body.text.actions.link.metadata.description
object
Mostrar parámetros secundarios
body.text.actions.link.metadata.description.label
string
obligatorio
body.text.actions.link.text
string
obligatorio
body.text.actions.link.url
string
obligatorio
body.text.actions.type
string
obligatorio
Possible values: link
body.text.attachments
array of object
Mostrar parámetros secundarios
body.text.attachments.content
string
body.text.attachments.contentId
string
body.text.attachments.contentType
string
body.text.attachments.filename
string
obligatorio
body.text.attachments.inline
boolean
body.text.attachments.mediaUrl
string
obligatorio
body.text.metadata
object
Mostrar parámetros secundarios
body.text.metadata.apple
object
Mostrar parámetros secundarios
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
Mostrar parámetros secundarios
body.text.metadata.line.emoji
object
Mostrar parámetros secundarios
body.text.metadata.line.emoji.items
array of object
Mostrar parámetros secundarios
body.text.metadata.line.emoji.items.emojiId
string
obligatorio
body.text.metadata.line.emoji.items.index
integer
obligatorio
body.text.metadata.line.emoji.items.length
integer
body.text.metadata.line.emoji.items.productId
string
obligatorio
body.text.metadata.paymentDetails
object
Mostrar parámetros secundarios
body.text.metadata.paymentDetails.amount
string
obligatorio
body.text.metadata.paymentDetails.currency
string
obligatorio
body.text.metadata.paymentDetails.sessionIdentifier
string
body.text.metadata.paymentDetails.state
string
obligatorio
body.text.metadata.subject
string
body.text.metadata.telegram
object
Mostrar parámetros secundarios
body.text.metadata.telegram.parseMode
string
body.text.metadata.whatsapp
object
Mostrar parámetros secundarios
body.text.metadata.whatsapp.callPermissionExpiration
string
body.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
body.text.metadata.whatsapp.previewUrl
boolean
obligatorio
body.text.metadata.whatsapp.sharedContacts
array of object
Mostrar parámetros secundarios
body.text.metadata.whatsapp.sharedContacts.origin
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones
array of object
Mostrar parámetros secundarios
body.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.vcard
string
body.text.text
string
obligatorio
body.type
string
obligatorio
Possible values: text
replyTo
object
Mostrar parámetros secundarios
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.
Mostrar parámetros secundarios
Create a participant of the type user, access key, flow, agent, bot, or action rule.
participants.id
string
obligatorio
The ID of the user, access key, flow, agent, bot, or action rule.
participants.type
string
obligatorio
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.
Mostrar parámetros secundarios
meta.email
object
Metadata fields for email messages.
Mostrar parámetros secundarios
meta.email.subject
string
Email subject line.
meta.email.headers
object
Additional email headers.
meta.email.from
object
Email From address.
Mostrar parámetros secundarios
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.
Mostrar parámetros secundarios
meta.referral.source
string
meta.referral.title
string
meta.referral.text
string
meta.referral.group
string
meta.referral.metadata
object
Mostrar parámetros secundarios
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
Cuerpo de la respuesta
body
object
Mostrar atributos secundarios
body.text
object
obligatorio
Mostrar atributos secundarios
body.text.actions
array of object
Mostrar atributos secundarios
body.text.actions.link
object
obligatorio
Mostrar atributos secundarios
body.text.actions.link.metadata
object
Mostrar atributos secundarios
body.text.actions.link.metadata.description
object
Mostrar atributos secundarios
body.text.actions.link.metadata.description.label
string
obligatorio
body.text.actions.link.text
string
obligatorio
body.text.actions.link.url
string
obligatorio
body.text.actions.type
string
obligatorio
Possible values: link
body.text.attachments
array of object
Mostrar atributos secundarios
body.text.attachments.content
string
body.text.attachments.contentId
string
body.text.attachments.contentType
string
body.text.attachments.filename
string
obligatorio
body.text.attachments.inline
boolean
body.text.attachments.mediaUrl
string
obligatorio
body.text.metadata
object
Mostrar atributos secundarios
body.text.metadata.apple
object
Mostrar atributos secundarios
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
Mostrar atributos secundarios
body.text.metadata.line.emoji
object
Mostrar atributos secundarios
body.text.metadata.line.emoji.items
array of object
Mostrar atributos secundarios
body.text.metadata.line.emoji.items.emojiId
string
obligatorio
body.text.metadata.line.emoji.items.index
integer
obligatorio
body.text.metadata.line.emoji.items.length
integer
body.text.metadata.line.emoji.items.productId
string
obligatorio
body.text.metadata.paymentDetails
object
Mostrar atributos secundarios
body.text.metadata.paymentDetails.amount
string
obligatorio
body.text.metadata.paymentDetails.currency
string
obligatorio
body.text.metadata.paymentDetails.sessionIdentifier
string
body.text.metadata.paymentDetails.state
string
obligatorio
body.text.metadata.subject
string
body.text.metadata.telegram
object
Mostrar atributos secundarios
body.text.metadata.telegram.parseMode
string
body.text.metadata.whatsapp
object
Mostrar atributos secundarios
body.text.metadata.whatsapp.callPermissionExpiration
string
body.text.metadata.whatsapp.callPermissionResponse
string
Possible values: accept, reject
body.text.metadata.whatsapp.previewUrl
boolean
obligatorio
body.text.metadata.whatsapp.sharedContacts
array of object
Mostrar atributos secundarios
body.text.metadata.whatsapp.sharedContacts.origin
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones
array of object
Mostrar atributos secundarios
body.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatorio
body.text.metadata.whatsapp.sharedContacts.vcard
string
body.text.text
string
obligatorio
body.type
string
obligatorio
Possible values: text
channelId
string
conversationCreatedAt
string
conversationId
string
obligatorio
createdAt
string
obligatorio
draft
boolean
obligatorio
Whether this message is a draft.
draftMeta
object
Metadata for draft messages.
Mostrar atributos secundarios
draftMeta.creatorType
string
obligatorio
Possible values: user, bot
id
string
obligatorio
A unique identifier for this message.
interactions
array of object
A list of interactions associated with the message (e.g. read receipts, clicks, reactions).
Mostrar atributos secundarios
interactions.bodyTemplateProjectId
string
interactions.channelId
string
obligatorio
interactions.context
object
obligatorio
Mostrar atributos secundarios
interactions.context.id
string
interactions.context.tagIds
array of string
interactions.context.type
string
interactions.createdAt
string
obligatorio
interactions.details
string
interactions.id
string
obligatorio
interactions.isFirstInteraction
boolean
interactions.isFirstInteractionIncludingBots
boolean
interactions.journey
object
Mostrar atributos secundarios
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
obligatorio
interactions.messagePartsCount
integer
obligatorio
interactions.messageReference
string
obligatorio
interactions.messageTags
array of string
interactions.metadata
object
Mostrar atributos secundarios
interactions.metadata.button
object
Mostrar atributos secundarios
interactions.metadata.button.payload
string
obligatorio
interactions.metadata.conversion
object
Mostrar atributos secundarios
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
Mostrar atributos secundarios
interactions.metadata.link.clickType
string
Possible values: link, button
interactions.metadata.link.name
string
obligatorio
interactions.metadata.link.url
string
obligatorio
interactions.metadata.prefetched
boolean
interactions.metadata.reaction
object
Mostrar atributos secundarios
interactions.metadata.reaction.action
string
obligatorio
Possible values: react, unreact
interactions.metadata.reaction.emoji
string
obligatorio
interactions.metadata.renderedContentBlocks
array of string
interactions.metadata.subscriptionList
object
Mostrar atributos secundarios
interactions.metadata.subscriptionList.subscriptionListId
string
obligatorio
interactions.notification
object
Mostrar atributos secundarios
interactions.notification.template
string
interactions.notification.url
string
obligatorio
interactions.platformId
string
obligatorio
interactions.platformReferenceId
string
interactions.receiver
object
obligatorio
Mostrar atributos secundarios
interactions.receiver.connector
object
Mostrar atributos secundarios
interactions.receiver.connector.annotations
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Mostrar atributos secundarios
interactions.receiver.connector.annotations.name
string
interactions.receiver.connector.id
string
obligatorio
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
Mostrar atributos secundarios
interactions.receiver.contacts.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Mostrar atributos secundarios
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.
Mostrar atributos secundarios
interactions.receiver.contacts.identifiers.identifierKey
string
obligatorio
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
interactions.receiver.contacts.identifiers.identifierValue
string
obligatorio
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
Mostrar atributos secundarios
interactions.receiver.device.gateway
string
obligatorio
Possible values: firebase, apns, web
interactions.receiver.device.id
string
obligatorio
interactions.receiver.device.identifierValue
string
obligatorio
interactions.receiver.inbox
object
Mostrar atributos secundarios
interactions.receiver.inbox.emailRecipientType
string
interactions.receiver.inbox.id
string
obligatorio
interactions.receiver.inbox.identifierKey
string
obligatorio
interactions.receiver.inbox.identifierValue
string
obligatorio
interactions.receiver.inbox.type
string
obligatorio
Possible values: user, group
interactions.receiver.userContacts
array of object
Mostrar atributos secundarios
interactions.receiver.userContacts.id
string
obligatorio
interactions.receiver.userContacts.identifierKey
string
obligatorio
interactions.receiver.userContacts.identifierValue
string
obligatorio
interactions.receiver.userContacts.type
string
interactions.type
string
obligatorio
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
Mostrar atributos secundarios
meta.campaign
object
Mostrar atributos secundarios
meta.campaign.id
string
meta.campaign.name
string
meta.campaignId
string
meta.chargeOnceDelivered
boolean
meta.email
object
Mostrar atributos secundarios
meta.email.from
object
Mostrar atributos secundarios
meta.email.from.displayName
string
meta.email.from.username
string
meta.email.headers
object
meta.email.subject
string
meta.extraInformation
object
meta.flow
object
Mostrar atributos secundarios
meta.flow.id
string
meta.flow.name
string
meta.flow.runId
string
meta.flow.scheduleExecutionId
string
meta.flow.stepId
string
meta.formResponse
object
Mostrar atributos secundarios
meta.formResponse.id
string
obligatorio
meta.formResponse.jsonResponse
string
obligatorio
meta.formResponse.requestIdentifier
string
obligatorio
meta.formResponse.selections
array of object
Mostrar atributos secundarios
meta.formResponse.selections.items
array of object
Mostrar atributos secundarios
meta.formResponse.selections.items.identifier
string
obligatorio
meta.formResponse.selections.items.title
string
obligatorio
meta.formResponse.selections.items.type
string
obligatorio
meta.formResponse.selections.items.value
string
obligatorio
meta.formResponse.selections.pageIdentifier
string
obligatorio
meta.formResponse.selections.subtitle
string
obligatorio
meta.formResponse.selections.title
string
obligatorio
meta.formResponse.sessionIdentifier
string
obligatorio
meta.formResponse.template
string
obligatorio
meta.formResponse.version
string
obligatorio
meta.ignoreGlobalHoldout
boolean
meta.ignoreQuietHours
boolean
meta.journey
object
Mostrar atributos secundarios
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.
Mostrar atributos secundarios
meta.order.products
array of object
Mostrar atributos secundarios
meta.order.products.externalCatalogId
string
The platform-specific catalog ID of the product.
meta.order.products.externalProductId
string
obligatorio
The platform-specific product ID.
meta.order.products.price
object
obligatorio
Mostrar atributos secundarios
meta.order.products.price.amount
integer
obligatorio
meta.order.products.price.currencyCode
string
obligatorio
meta.order.products.price.exponent
integer
obligatorio
meta.order.products.quantity
integer
obligatorio
The number of items purchased.
meta.pushNotifications
object
Mostrar atributos secundarios
meta.pushNotifications.gatewayTypeOverride
string
Possible values: firebase, apns, web
meta.referral
object
Mostrar atributos secundarios
meta.referral.group
string
meta.referral.metadata
object
Mostrar atributos secundarios
meta.referral.metadata.caption
string
meta.referral.metadata.mediaType
string
meta.referral.metadata.mediaUrl
string
meta.referral.metadata.sourceId
string
obligatorio
meta.referral.metadata.sourceUrl
string
meta.referral.metadata.timestamp
string
meta.referral.metadata.trackingId
string
meta.referral.metadata.username
string
meta.referral.source
string
obligatorio
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).
Mostrar atributos secundarios
meta.referredProduct.externalCatalogId
string
The platform-specific catalog ID of the product.
meta.referredProduct.externalProductId
string
obligatorio
The platform-specific product ID.
meta.renderedContentBlocks
array of string
meta.shortToLongLinks
object
meta.skipThisMessage
string
Possible values: campaignHoldout, globalHoldout, journeyHoldout
meta.sms
object
Mostrar atributos secundarios
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
Mostrar atributos secundarios
meta.sms.smpp.segments
array of object
Mostrar atributos secundarios
meta.sms.smpp.segments.id
string
obligatorio
meta.sms.smpp.segments.registeredDelivery
string
obligatorio
Possible values: final, intermediate, all, noDlr
meta.sms.smpp.userId
string
obligatorio
meta.sms.validity
string
meta.useFallback
boolean
reason
string
Failure reason. Populated when status is sending_failed or delivery_failed.
receiver
object
Mostrar atributos secundarios
receiver.connector
object
Mostrar atributos secundarios
receiver.connector.annotations
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Mostrar atributos secundarios
receiver.connector.annotations.name
string
receiver.connector.id
string
obligatorio
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
Mostrar atributos secundarios
receiver.contacts.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Mostrar atributos secundarios
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.
Mostrar atributos secundarios
receiver.contacts.identifiers.identifierKey
string
obligatorio
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
receiver.contacts.identifiers.identifierValue
string
obligatorio
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
Mostrar atributos secundarios
receiver.device.gateway
string
obligatorio
Possible values: firebase, apns, web
receiver.device.id
string
obligatorio
receiver.device.identifierValue
string
obligatorio
receiver.inbox
object
Mostrar atributos secundarios
receiver.inbox.emailRecipientType
string
receiver.inbox.id
string
obligatorio
receiver.inbox.identifierKey
string
obligatorio
receiver.inbox.identifierValue
string
obligatorio
receiver.inbox.type
string
obligatorio
Possible values: user, group
receiver.userContacts
array of object
Mostrar atributos secundarios
receiver.userContacts.id
string
obligatorio
receiver.userContacts.identifierKey
string
obligatorio
receiver.userContacts.identifierValue
string
obligatorio
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
Mostrar atributos secundarios
recipients.contactAnnotation
object
Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.
Mostrar atributos secundarios
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.
Mostrar atributos secundarios
recipients.identifiers.identifierKey
string
obligatorio
The identifier key for finding the contact (e.g. emailaddress, phonenumber).
recipients.identifiers.identifierValue
string
obligatorio
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
obligatorio
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
Mostrar atributos secundarios
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
obligatorio
Mostrar atributos secundarios
sender.email
string
sender.name
string
sender.avatarUrl
string
sender.contact
object
Mostrar atributos secundarios
sender.contact.identifierKey
string
obligatorio
sender.contact.identifierValue
string
obligatorio
sender.contact.platformAddress
string
sender.contact.platformAddressSelector
string
sender.conversationId
string
sender.createdAt
string
sender.displayName
string
sender.id
string
obligatorio
sender.resourceUri
string
sender.status
string
Possible values: invited, pending, active, inactive
sender.type
string
obligatorio
Possible values: user, contact, agent, flow, bot, accessKey, channel, connector, collaborationAutomation
sender.updatedAt
string
source
string
obligatorio
Possible values: conversations, channels, bots, external
status
string
obligatorio
Possible values: accepted, processing, sent, sending_failed, delivered, delivery_failed, deleted
template
object
Mostrar atributos secundarios
template.attachments
array of object
Mostrar atributos secundarios
template.attachments.content
string
template.attachments.contentType
string
template.attachments.filename
string
obligatorio
template.attachments.inline
boolean
obligatorio
template.attachments.mediaUrl
string
obligatorio
template.deployment
object
template.locale
string
obligatorio
template.name
string
The platform name of the template.
template.parameters
array of object
Mostrar atributos secundarios
template.parameters.key
string
obligatorio
template.parameters.sourceUrl
object
Mostrar atributos secundarios
template.parameters.sourceUrl.fullyReplaced
boolean
obligatorio
template.parameters.sourceUrl.value
string
obligatorio
template.parameters.type
string
obligatorio
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
obligatorio
template.projectId
string
obligatorio
The ID of the project from Studio.
template.settings
object
Mostrar atributos secundarios
template.settings.disallowMmLite
boolean
template.shortLinks
object
Mostrar atributos secundarios
template.shortLinks.domain
string
obligatorio
The domain to use when shortening links. When set to default, uses the default link shortening domain for the workspace.
template.shortLinks.enabled
boolean
obligatorio
Enables link shortening for SMS messages.
template.templateBody
object
Mostrar atributos secundarios
template.templateBody.text
object
obligatorio
Mostrar atributos secundarios
template.templateBody.text.actions
array of object
Mostrar atributos secundarios
template.templateBody.text.actions.link
object
obligatorio
Mostrar atributos secundarios
template.templateBody.text.actions.link.metadata
object
Mostrar atributos secundarios
template.templateBody.text.actions.link.metadata.description
object
Mostrar atributos secundarios
template.templateBody.text.actions.link.metadata.description.label
string
obligatorio
template.templateBody.text.actions.link.text
string
obligatorio
template.templateBody.text.actions.link.url
string
obligatorio
template.templateBody.text.actions.type
string
obligatorio
Possible values: link
template.templateBody.text.attachments
array of object
Mostrar atributos secundarios
template.templateBody.text.attachments.content
string
template.templateBody.text.attachments.contentId
string
template.templateBody.text.attachments.contentType
string
template.templateBody.text.attachments.filename
string
obligatorio
template.templateBody.text.attachments.inline
boolean
template.templateBody.text.attachments.mediaUrl
string
obligatorio
template.templateBody.text.metadata
object
Mostrar atributos secundarios
template.templateBody.text.metadata.apple
object
Mostrar atributos secundarios
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
Mostrar atributos secundarios
template.templateBody.text.metadata.line.emoji
object
Mostrar atributos secundarios
template.templateBody.text.metadata.line.emoji.items
array of object
Mostrar atributos secundarios
template.templateBody.text.metadata.line.emoji.items.emojiId
string
obligatorio
template.templateBody.text.metadata.line.emoji.items.index
integer
obligatorio
template.templateBody.text.metadata.line.emoji.items.length
integer
template.templateBody.text.metadata.line.emoji.items.productId
string
obligatorio
template.templateBody.text.metadata.paymentDetails
object
Mostrar atributos secundarios
template.templateBody.text.metadata.paymentDetails.amount
string
obligatorio
template.templateBody.text.metadata.paymentDetails.currency
string
obligatorio
template.templateBody.text.metadata.paymentDetails.sessionIdentifier
string
template.templateBody.text.metadata.paymentDetails.state
string
obligatorio
template.templateBody.text.metadata.subject
string
template.templateBody.text.metadata.telegram
object
Mostrar atributos secundarios
template.templateBody.text.metadata.telegram.parseMode
string
template.templateBody.text.metadata.whatsapp
object
Mostrar atributos secundarios
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
obligatorio
template.templateBody.text.metadata.whatsapp.sharedContacts
array of object
Mostrar atributos secundarios
template.templateBody.text.metadata.whatsapp.sharedContacts.origin
string
obligatorio
template.templateBody.text.metadata.whatsapp.sharedContacts.phones
array of object
Mostrar atributos secundarios
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.phone
string
obligatorio
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.type
string
obligatorio
template.templateBody.text.metadata.whatsapp.sharedContacts.phones.waId
string
obligatorio
template.templateBody.text.metadata.whatsapp.sharedContacts.vcard
string
template.templateBody.text.text
string
obligatorio
template.templateBody.type
string
obligatorio
Possible values: text
template.utmParameters
array of object
Mostrar atributos secundarios
template.utmParameters.key
string
obligatorio
template.utmParameters.value
string
obligatorio
template.variables
object
template.version
string
obligatorio
The version of the template.
type
string
Possible values: text, html, image, file, gif, location, carousel, list, section, authentication, action
updatedAt
string
obligatorio
Ejemplo de código
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Examples

Sending a simple message

Ejemplo de código
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

Ejemplo de código
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
}'