# 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
## Create message in conversation > 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.
```json {"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[{"name":"conversation_message","description":"Manage the messages of a conversation."}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"conversationIdOrNil":{"name":"conversationId","description":"The conversation ID","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"CreateMessage":{"oneOf":[{"type":"object","description":"A message specifying its contents through a `body` field.","title":"Message with body","additionalProperties":false,"required":["body","participantId","participantType"],"properties":{"draft":{"type":"boolean","description":"Whether this message is a draft."},"reference":{"$ref":"#/components/schemas/MessageReference"},"sender":{"$ref":"#/components/schemas/MessageSender"},"participantId":{"$ref":"#/components/schemas/ParticipantId"},"replyToMessageId":{"$ref":"#/components/schemas/MessageReplyToMessageId"},"participantType":{"$ref":"#/components/schemas/CreateMessageParticipantType"},"participantContactIdentifierKey":{"type":"string","description":"The key of the contact identifier to use for the participant. This is used when the participant is not a user in the system.\n"},"participantContactIdentifierValue":{"type":"string"},"recipients":{"$ref":"#/components/schemas/CreateMessageRecipients"},"addMissingParticipants":{"type":"boolean","description":"If enabled, conveniently adds missing participants to the conversation without requiring additional API calls to `/participants`. It's recommended to set this to `true`.\n"},"body":{"$ref":"#/components/schemas/Body"},"replyTo":{"$ref":"#/components/schemas/MessageReplyTo"},"appendPreviousMessage":{"type":"boolean","default":true},"channelId":{"$ref":"#/components/schemas/ChannelId"},"participants":{"type":"array","description":"When creating a new conversation, this is the list of participants.","items":{"$ref":"#/components/schemas/ParticipantRef"}},"name":{"type":"string","description":"When creating a new conversation, this is the subject of the email."},"description":{"type":"string","description":"When creating a new conversation, this is the description associated with it."},"visibility":{"$ref":"#/components/schemas/ConversationVisibility"},"accessibility":{"$ref":"#/components/schemas/ConversationAccessibility"},"attributes":{"type":"object","description":"A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.\n","nullable":true,"additionalProperties":true},"meta":{"$ref":"#/components/schemas/MessageMeta"}}},{"type":"object","description":"A message specifying its contents through a `template` field.","title":"Message with template","additionalProperties":false,"required":["template","participantId","participantType"],"properties":{"draft":{"type":"boolean","description":"Whether this message is a draft."},"reference":{"$ref":"#/components/schemas/MessageReference"},"sender":{"$ref":"#/components/schemas/MessageSender"},"participantId":{"$ref":"#/components/schemas/ParticipantId"},"replyToMessageId":{"$ref":"#/components/schemas/MessageReplyToMessageId"},"participantType":{"$ref":"#/components/schemas/CreateMessageParticipantType"},"recipients":{"$ref":"#/components/schemas/CreateMessageRecipients"},"addMissingParticipants":{"type":"boolean","description":"If enabled, conveniently adds missing participants to the conversation without requiring additional API calls to `/participants`. It's recommended to set this to `true`.\n"},"template":{"$ref":"#/components/schemas/Template"},"appendPreviousMessage":{"type":"boolean","default":true},"channelId":{"$ref":"#/components/schemas/ChannelId"},"participants":{"type":"array","description":"When creating a new conversation, this is the list of participants.","items":{"$ref":"#/components/schemas/ParticipantRef"}},"name":{"type":"string","description":"When creating a new conversation, this is the subject of the email."},"description":{"type":"string","description":"When creating a new conversation, this is the description associated with it."},"visibility":{"$ref":"#/components/schemas/ConversationVisibility"},"accessibility":{"$ref":"#/components/schemas/ConversationAccessibility"},"attributes":{"type":"object","description":"A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.\n","nullable":true,"additionalProperties":true},"meta":{"$ref":"#/components/schemas/MessageMeta"}}}]},"MessageReference":{"type":"string","description":"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.\n","minLength":1,"maxLength":60,"nullable":true},"MessageSender":{"type":"object","description":"Message sender information for email.","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","description":"Sender name shown in the email \"From\" header."},"email":{"type":"string","description":"Sender email address."},"emailReplyToAddress":{"type":"string","description":"Sender email address to reply to."}}},"ParticipantId":{"type":"string","description":"Participant ID.","maxLength":255},"MessageReplyToMessageId":{"type":"string","format":"uuid","description":"Message ID to reply to. Only used for email channels, other channel types must use `replyTo`."},"CreateMessageParticipantType":{"type":"string","description":"Participant type. When sending messages through the Conversations API, the participant be one of `accessKey`, `flow`, or `contact`.\n","enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"]},"CreateMessageRecipients":{"type":"array","description":"List of recipients.","nullable":true,"items":{"$ref":"#/components/schemas/CreateMessageRecipient"}},"CreateMessageRecipient":{"type":"object","nullable":true,"oneOf":[{"type":"object","title":"MessageRecipientWithoutContact","description":"Create a new recipient by specifying an identifier key and identifier value.\nFor more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"required":["identifierValue","type"],"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address."},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","maxLength":100},"type":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]}}},{"type":"object","title":"MessageRecipientWithContact","description":"Create a new recipient for a message.\n","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"Contact ID."},"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used.","nullable":true},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address","nullable":true},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","maxLength":100,"nullable":true},"type":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]}}}]},"Body":{"type":"object","title":"MessageBody","nullable":true,"allOf":[{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/BodyTypes"}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeHTML"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"},{"$ref":"#/components/schemas/TypeSection"},{"$ref":"#/components/schemas/TypeAuthentication"},{"$ref":"#/components/schemas/TypeAction"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","html":"#/components/schemas/TypeHTML","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList","section":"#/components/schemas/TypeSection","authentication":"#/components/schemas/TypeAuthentication","action":"#/components/schemas/TypeAction"}}}]},"BodyTypes":{"type":"string","enum":["text","html","image","file","gif","location","carousel","list","section","authentication","template","action"]},"TypeText":{"type":"object","required":["text","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","filename"],"properties":{"mediaUrl":{"type":"string","format":"uri"},"filename":{"type":"string"},"inline":{"type":"boolean"},"contentId":{"type":"string"}}}},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","additionalProperties":false,"properties":{"subject":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"whatsapp":{"type":"object","additionalProperties":false,"properties":{"previewUrl":{"type":"boolean","description":"When set to `true`, preview will be displayed within whatsapp chat."}}},"line":{"type":"object","additionalProperties":false,"properties":{"emoji":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["index","productId","emojiId"],"properties":{"index":{"type":"integer"},"productId":{"type":"string"},"emojiId":{"type":"string"},"length":{"type":"integer","nullable":true,"readOnly":true}}}}}}}},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"},"apple":{"$ref":"#/components/schemas/MetadataApple"}}}}}}},"Actions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Action"}},"Action":{"allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["link","reply","locationRequest","buy","postback"]}}},{"oneOf":[{"$ref":"#/components/schemas/ActionLink"},{"$ref":"#/components/schemas/ActionReply"},{"$ref":"#/components/schemas/ActionLocationRequest"},{"$ref":"#/components/schemas/ActionBuy"},{"$ref":"#/components/schemas/ActionPostback"}],"discriminator":{"propertyName":"type","mapping":{"link":"#/components/schemas/ActionLink","reply":"#/components/schemas/ActionReply","locationRequest":"#/components/schemas/ActionLocationRequest","buy":"#/components/schemas/ActionBuy","postback":"#/components/schemas/ActionPostback"}}}]},"ActionLink":{"type":"object","required":["link","type"],"properties":{"type":{"type":"string","enum":["link"]},"link":{"type":"object","required":["text","url"],"properties":{"text":{"type":"string"},"url":{"anyOf":[{"type":"string","pattern":"{{[^{}]+}}"},{"type":"string","format":"uri"}]}}}}},"ActionReply":{"type":"object","required":["reply","type"],"properties":{"type":{"type":"string","enum":["reply"]},"reply":{"type":"object","properties":{"text":{"type":"string"},"imageUrl":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ActionReplyMetadata"}},"required":["text"]}}},"ActionReplyMetadata":{"type":"object","properties":{"description":{"$ref":"#/components/schemas/ActionDescription"}}},"ActionDescription":{"type":"object","description":"Sets the description in the row objects for Whatsapp list messages. Only available usage for Whatsapp platform","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":72}}},"ActionLocationRequest":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["locationRequest"]},"locationRequest":{"type":"object","nullable":true,"properties":{"text":{"type":"string","default":"Send location"}}}}},"ActionBuy":{"type":"object","required":["buy","type"],"properties":{"type":{"type":"string","enum":["buy"]},"buy":{"type":"object","properties":{"text":{"type":"string"},"amountCents":{"type":"integer"},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["text","amountCents","currency"]}}},"ActionPostback":{"type":"object","required":["postback","type"],"properties":{"type":{"type":"string","enum":["postback"]},"postback":{"type":"object","properties":{"text":{"type":"string"},"payload":{"type":"string"},"imageUrl":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ActionPostbackMetadata"}},"required":["text"]}}},"ActionPostbackMetadata":{"type":"object","properties":{"description":{"$ref":"#/components/schemas/ActionDescription"}}},"MetadataTelegram":{"type":"object","description":"The property is specific to Telegram, indicating the markup type to be used for message formatting","additionalProperties":false,"properties":{"parseMode":{"type":"string","enum":["Markdown","MarkdownV2"]}}},"MetadataApple":{"type":"object","description":"The property is specific to Apple Business Chat, containing Apple-specific metadata","additionalProperties":false,"properties":{"summaryText":{"type":"string","description":"Summary text for Apple Business Chat messages"},"appClipPreview":{"type":"boolean","description":"Indicates if the message includes an App Clip link"},"appClipRegion":{"type":"string","description":"AppClipRegion is the ISO 3166 alpha-2 country code for the App Store region."}}},"TypeHTML":{"type":"object","required":["html","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["html"]},"html":{"type":"object","additionalProperties":false,"anyOf":[{"required":["text"]},{"required":["html"]}],"properties":{"text":{"type":"string","minLength":1},"html":{"type":"string","minLength":1},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"anyOf":[{"required":["mediaUrl","filename"]},{"required":["content","contentType","filename"]}],"properties":{"mediaUrl":{"type":"string","format":"uri"},"filename":{"type":"string"},"inline":{"type":"boolean"},"content":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"contentId":{"type":"string"}}}},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","additionalProperties":false,"properties":{"subject":{"type":"string"},"emailFrom":{"type":"object","additionalProperties":false,"properties":{"username":{"type":"string","pattern":"[\\w\\d.-/+]+"},"displayName":{"type":"string"}}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"initialOpenTracking":{"type":"boolean"},"clickTracking":{"type":"boolean"},"openTracking":{"type":"boolean"}}}}}}},"TypeImage":{"type":"object","required":["image","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","additionalProperties":false,"required":["images"],"properties":{"text":{"type":"string"},"images":{"type":"array","minLength":1,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string","format":"uri","minLength":1},"altText":{"type":"string"}}}},"metadata":{"type":"object","properties":{"subject":{"type":"string","description":"The property is specific mms file, shows the subject of the mms."},"fallbackText":{"type":"string","description":"The property is specific mms file, when a mms is not supported, it will fallback to show content with the fallbackText."},"storyType":{"type":"string","description":"The property is specific instagram file, shows the story type."},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}},"actions":{"$ref":"#/components/schemas/Actions"}}}}},"TypeFile":{"type":"object","required":["file","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["file"]},"file":{"type":"object","additionalProperties":false,"required":["files"],"properties":{"text":{"type":"string"},"files":{"type":"array","minLength":1,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","contentType"],"properties":{"mediaUrl":{"type":"string","format":"uri","minLength":1},"contentType":{"type":"string","minLength":1},"filename":{"type":"string"},"altText":{"type":"string"},"metadata":{"type":"object","properties":{"isAnimated":{"type":"boolean","description":"The property is specific the sticker file, shows that if the sticker is animated or not."}}}}}},"metadata":{"type":"object","properties":{"subject":{"type":"string","description":"The property is specific mms file, shows the subject of the mms."},"fallbackText":{"type":"string","description":"The property is specific mms file, when a mms is not supported, it will fallback to show content with the fallbackText."},"storyType":{"type":"string","description":"The property is specific instagram file, shows the story type."},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}},"actions":{"$ref":"#/components/schemas/Actions"}}}}},"TypeGif":{"type":"object","required":["gif","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["gif"]},"gif":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"text":{"type":"string"},"mediaUrl":{"type":"string","format":"uri","minLength":1},"altText":{"type":"string"},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","properties":{"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}}}}}},"TypeLocation":{"type":"object","required":["location","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["location"]},"location":{"type":"object","additionalProperties":false,"required":["coordinates"],"properties":{"coordinates":{"type":"object","additionalProperties":false,"properties":{"latitude":{"type":"number","format":"float","minimum":-90,"maximum":90},"longitude":{"type":"number","format":"float","minimum":-180,"maximum":180}}},"location":{"type":"object","additionalProperties":false,"properties":{"address":{"type":"string"},"label":{"type":"string"}}}}}}},"TypeCarousel":{"type":"object","required":["carousel","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["carousel"]},"carousel":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"text":{"type":"string","description":"Optional text displayed above the carousel cards","maxLength":1024},"items":{"$ref":"#/components/schemas/Items"}}}}},"Items":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"mediaUrl":{"type":"string","format":"uri","nullable":true},"description":{"type":"string"},"altText":{"type":"string"},"actions":{"$ref":"#/components/schemas/Actions"}}}},"TypeList":{"type":"object","required":["list","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["list"]},"list":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"text":{"type":"string"},"altText":{"type":"string"},"items":{"$ref":"#/components/schemas/Items"},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","properties":{"button":{"type":"object","description":"Sets a button name for whatsapp list messages. Only available usage for Whatsapp platform","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":20}}},"replyMessage":{"type":"object","description":"Sets the reply message to be used when a list item is picked. Used for Apple Business Chat.","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":512},"text":{"type":"string","maxLength":512}}}}}},"required":["text"]}}},"TypeSection":{"type":"object","required":["section","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["section"]},"section":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"minLength":1,"$ref":"#/components/schemas/SectionBody"}},"configurations":{"type":"object","additionalProperties":{"type":"string"}}}}}},"SectionBody":{"type":"object","title":"MessageBody","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","image","file","gif","location","carousel","list","section"]}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"},{"$ref":"#/components/schemas/TypeSectionNested"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList","section":"#/components/schemas/TypeSectionNested"}}}]},"TypeSectionNested":{"type":"object","required":["section","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["section"]},"section":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"minLength":1,"$ref":"#/components/schemas/SectionBodyNested"}},"configurations":{"type":"object","properties":{"default":{"type":"string"}},"additionalProperties":{"type":"string"}}}}}},"SectionBodyNested":{"type":"object","title":"MessageBody","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","image","file","gif","location","carousel","list"]}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList"}}}]},"TypeAuthentication":{"type":"object","required":["authentication","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["authentication"]},"authentication":{"type":"object","additionalProperties":false,"properties":{"otp":{"type":"object","additionalProperties":false,"required":["disclaimer"],"properties":{"disclaimer":{"type":"boolean","description":"Whether to add a security disclaimer to the authentication body.","nullable":false},"expirationTime":{"type":"integer","minimum":1,"maximum":90,"nullable":true,"description":"The number of seconds after which the authentication body will expire. If not set, no expiration notification will be sent."},"actions":{"$ref":"#/components/schemas/Actions"}}}}}}},"TypeAction":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["permission_request"]},"permission_request":{"type":"object","required":["resource"],"properties":{"resource":{"type":"string","enum":["call"]}}}}},"MessageReplyTo":{"type":"object","description":"A conversation message being replied to. Only applies for non-email channels.","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the message being replied to."},"order":{"type":"integer","description":"Index of a multipart message. If not replying to a multipart message this field can be omitted."},"type":{"type":"string","description":"Must always be `message`.","enum":["message","click","referrals"]}},"required":["id","type"]},"ChannelId":{"type":"string","description":"Channel ID.","format":"uuid"},"ParticipantRef":{"type":"object","description":"The participantRef is used for creating participants.\n","oneOf":[{"type":"object","title":"Non-contact participant with ID","description":"Create a participant of the type user, access key, flow, agent, bot, or action rule.\n","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"The ID of the user, access key, flow, agent, bot, or action rule."},"type":{"type":"string","description":"Participant type.","enum":["user","accessKey","flow","agent","bot","collaborationAutomation"]}}},{"type":"object","title":"Participant with identifier","description":"Create a participant of the type contact and user the identifier to find the contact.\nFor more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\nWhen platformAddressSelector is provided, the identifierKey/identifierValue will be used to find the contact, and the platformAddressSelector to select the attribute used for the platform communication.\n","additionalProperties":false,"required":["type","identifierValue"],"properties":{"id":{"type":"string","description":"The contact ID.","format":"uuid"},"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address."},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","maxLength":100},"type":{"type":"string","description":"Participant type.","enum":["contact"]}}},{"type":"object","title":"Participant with contact ID","description":"Create a participant based on an existing contact. It is optional to set the platformAddressSelector for a given contact to select the attribute used for the platform communication.\n","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"The contact ID.","format":"uuid"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","maxLength":100},"type":{"type":"string","description":"Participant type.","enum":["contact"]}}}]},"ConversationVisibility":{"type":"string","description":"Whether the conversation is public or private.","enum":["public","private","direct","group"],"default":"public"},"ConversationAccessibility":{"type":"string","description":"Indicates the access level for new participants to join the conversation.","enum":["open","invite-only","request-to-join","private"],"default":"open"},"MessageMeta":{"type":"object","description":"Message metadata fields that might be populated depending on the channel being used.","title":"MessageMeta","additionalProperties":false,"properties":{"email":{"type":"object","description":"Metadata fields for email messages.","additionalProperties":false,"properties":{"subject":{"type":"string","description":"Email subject line."},"headers":{"type":"object","description":"Additional email headers.","additionalProperties":{"type":"string"}},"from":{"type":"object","description":"Email From address.","additionalProperties":false,"properties":{"username":{"type":"string","description":"The username part of the adress, e.g. for the address `john.doe@bird.com`, this value will be `john.doe`.\n","pattern":"[\\w\\d.-/+]+"},"displayName":{"type":"string","description":"The display name of an email participant."}}}}},"extraInformation":{"type":"object","description":"A free-form object that might contain additional metadata fields.","additionalProperties":true},"referral":{"type":"object","description":"This represents a social media post or an ad that was referenced when starting the conversation.","additionalProperties":false,"properties":{"source":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"group":{"type":"string"},"metadata":{"type":"object","additionalProperties":false,"properties":{"sourceId":{"type":"string","description":"The ID of the social media post or ad."},"sourceUrl":{"type":"string","description":"The URL of the social media post or ad."},"mediaType":{"type":"string","description":"Type of media used in the post or ad."},"mediaUrl":{"type":"string","description":"Link to the media associated with the referral post or ad."},"caption":{"type":"string","description":"Caption associated with the referral post or ad."},"username":{"type":"string","description":"Username who created the referral post or ad."},"timestamp":{"type":"string","description":"Timestamp when the referral post or ad was created.","format":"date-time"},"trackingId":{"type":"string"}}}}}}},"Template":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"name":{"type":"string","description":"The platform name of the template."},"projectId":{"type":"string","description":"the ID of the project from the project from Studio"},"version":{"type":"string","description":"The version of the template."},"locale":{"type":"string","format":"locale-bcp47"},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","filename"],"properties":{"mediaUrl":{"type":"string","format":"uri","description":"The URL of the attachment."},"filename":{"type":"string","description":"The filename of the attachment."},"inline":{"type":"boolean"}}}},"shortLinks":{"nullable":true,"type":"object","description":"SMS link shortening options.","properties":{"enabled":{"type":"boolean","description":"Enables link shortening for SMS messages."},"domain":{"type":"string","description":"The domain to use when shortening links. When set to `default`,\nuses the default link shortening domain for the workspace.\n"}}},"variables":{"nullable":true,"deprecated":true,"description":"Deprecated: Use `parameters` instead (string parameter for variables). This property is maintained for backward compatibility but will be removed in a future version.\n","type":"object","properties":{"default":{"type":"string"}},"additionalProperties":{"type":"string"}},"utmParameters":{"nullable":true,"type":"array","description":"The list of UTM parameters.","minItems":1,"maxItems":8,"items":{"oneOf":[{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","description":"The name of the parameter in the query string.","minLength":1,"maxLength":20},"value":{"type":"string","description":"The static value of the parameter. Mutually exclusive with Reference.","minLength":1,"maxLength":100}}},{"type":"object","required":["key","reference"],"additionalProperties":false,"properties":{"key":{"type":"string","description":"The name of the parameter in the query string.","minLength":1,"maxLength":20},"reference":{"type":"string","description":"The reference to a dynamic value. Mutually exclusive with Value.","enum":["platform_name","channel_name"]}}}]}},"parameters":{"nullable":true,"type":"array","minLength":1,"items":{"$ref":"#/components/schemas/TemplateParameter"}},"settings":{"nullable":true,"type":"object","properties":{"disallowMmLite":{"type":"boolean","nullable":true,"description":"This is specific for WhatsApp marketing templates and requires MM Lite to be disabled for the WABAID.\n"}}}}},"TemplateParameter":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["string"]},"key":{"type":"string","minLength":1},"value":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["number"]},"key":{"type":"string","minLength":1},"value":{"type":"number"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["boolean"]},"key":{"type":"string","minLength":1},"value":{"type":"boolean"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["object"]},"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":true}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["sectionList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["sections"],"additionalProperties":false,"properties":{"sections":{"$ref":"#/components/schemas/Sections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["timeslotList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["timeslots"],"additionalProperties":false,"properties":{"timeslots":{"$ref":"#/components/schemas/Timeslots"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["productSections"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["productSections"],"additionalProperties":false,"properties":{"productSections":{"$ref":"#/components/schemas/ProductSections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["productList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["products"],"additionalProperties":false,"properties":{"products":{"$ref":"#/components/schemas/ProductList"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["shippingMethodList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["shippingMethods"],"additionalProperties":false,"properties":{"shippingMethods":{"$ref":"#/components/schemas/AppleShippingMethods"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["lineItemList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["lineItems"],"additionalProperties":false,"properties":{"lineItems":{"$ref":"#/components/schemas/AppleLineItems"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["whatsappProductSections"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["sections"],"additionalProperties":false,"properties":{"sections":{"$ref":"#/components/schemas/WhatsappProductSections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["whatsappProductItems"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["products"],"additionalProperties":false,"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappProductItem"}}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["carouselCards"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["cards"],"additionalProperties":false,"properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappCarouselCard"}}}}}}]},"Sections":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["title","items"],"properties":{"id":{"type":"string","nullable":true},"multipleSelection":{"type":"boolean"},"title":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReplyAction"}}}}},"ReplyAction":{"type":"object","required":["type","replyAction"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["reply-action"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"replyAction":{"type":"object","properties":{"text":{"type":"string"},"imageUrl":{"type":"string"},"payload":{"type":"string"},"subTitle":{"type":"string"}},"required":["text"]}}},"Timeslots":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["startTime","duration"],"properties":{"id":{"type":"string","nullable":true},"startTime":{"type":"string","format":"date-time"},"duration":{"type":"number"}}}},"ProductSections":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["title","products"],"properties":{"title":{"type":"string","minLength":1,"maxLength":24},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"Product":{"type":"object","additionalProperties":false,"required":["externalProductId"],"properties":{"externalProductId":{"type":"string"},"amount":{"type":"string"},"text":{"type":"string"}}},"ProductList":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["type","product"],"properties":{"type":{"type":"string","enum":["product"]},"product":{"$ref":"#/components/schemas/Product"}}}},"AppleShippingMethods":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["amount","label","identifier","detail"],"properties":{"amount":{"type":"string"},"label":{"type":"string"},"identifier":{"type":"string"},"detail":{"type":"string"}}}},"AppleLineItems":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["amount","text"],"properties":{"amount":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","enum":["pending","final"]}}}},"WhatsappProductSections":{"type":"array","nullable":false,"items":{"$ref":"#/components/schemas/WhatsappProductSection"}},"WhatsappProductSection":{"type":"object","additionalProperties":false,"required":["type","whatsappProductSection"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-product-section"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappProductSection":{"type":"object","additionalProperties":false,"required":["title","products"],"properties":{"title":{"type":"string","minLength":1,"maxLength":24},"products":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappProductItem"}}}}}},"WhatsappProductItem":{"type":"object","additionalProperties":false,"required":["type","whatsappProductItem"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-product-item"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappProductItem":{"type":"object","additionalProperties":false,"required":["externalProductId"],"properties":{"externalProductId":{"type":"string"}}}}},"WhatsappCarouselCard":{"type":"object","additionalProperties":false,"required":["type","whatsappCarouselCard"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-carousel-card"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappCarouselCard":{"type":"object","additionalProperties":false,"required":["header","body","actions"],"properties":{"header":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","image"],"properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string"},"altText":{"type":"string"}}}}},{"type":"object","additionalProperties":false,"required":["type","file"],"properties":{"type":{"type":"string","enum":["file"]},"file":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string"},"contentType":{"type":"string"}}}}}]},"body":{"type":"object","additionalProperties":false,"required":["type","text"],"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string"}}}}},"actions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","linkAction"],"properties":{"type":{"type":"string","enum":["link-action"]},"linkAction":{"type":"object","additionalProperties":false,"required":["text","url"],"properties":{"text":{"type":"string"},"url":{"type":"string"}}}}},"minItems":1,"maxItems":1,"description":"Session carousels only support one link action per card."}}}}},"Message":{"type":"object","description":"A conversation message.","additionalProperties":false,"required":["id","sender","draft","status","source","createdAt","updatedAt"],"anyOf":[{"required":["body"]},{"required":["template"]}],"properties":{"id":{"type":"string","description":"Message ID.","minLength":1},"conversationId":{"type":"string","description":"Conversation ID.","minLength":1},"reference":{"type":"string","description":"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.\n"},"sender":{"$ref":"#/components/schemas/Participant"},"draft":{"type":"boolean","description":"Whether this message is a draft."},"draftMeta":{"$ref":"#/components/schemas/DraftMessageMeta"},"replyToMessageId":{"type":"string","format":"uuid"},"recipients":{"type":"array","description":"Recipient list of this message.","items":{"$ref":"#/components/schemas/MessageRecipient"}},"status":{"$ref":"#/components/schemas/MessageStatus"},"source":{"type":"string","description":"Whether the message was created by Bird's Conversations API or an external party.","enum":["conversations","external"]},"template":{"$ref":"#/components/schemas/Template"},"body":{"$ref":"#/components/schemas/Body"},"reason":{"type":"string","description":"Failure reason. Will be populated if the status is `sending_failed` or `delivery_failed`."},"interactions":{"type":"array","description":"A list of interactions associated with the message.","nullable":true,"items":{"type":"object","description":"A message interaction.","additionalProperties":false,"required":["id","type","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for that interaction within its message."},"type":{"type":"string","description":"The type of interaction. `read` means the message was acknowledged as read, `opened means the email was opened, `click` means a link or button in the message was clicked, `report-as-spam` means the email was marked as spam by the recipient, `unsubscribe-request` means the recipient unsubscribed from receiving further emails, `delete-request` is a request for a message to be deleted, `reaction` represents an emoji reaction, and `invalid` means the interaction type is unknown.\n","enum":["read","opened","clicked","reported-as-spam","unsubscribe-request","delete-request","reaction","invalid"]},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"metadata":{"type":"object","description":"Metadata is a free-form object that can be used to store any additional information such as platform specific information\n","additionalProperties":true,"properties":{"link":{"type":"object","description":"Clicked link data. Will be populated if the interaction type is `clicked`.","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"button":{"type":"object","description":"Clicked button data. Will be populated if the interaction type is `clicked` on a message with buttons.","properties":{"payload":{"type":"string"}}},"reaction":{"type":"object","description":"Reaction data. Will be populated if the interaction type is `reaction`.","properties":{"emoji":{"type":"string"},"action":{"type":"string"}}}}}}}},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"updatedAt":{"type":"string","description":"Update timestamp formatted as RFC3339.","format":"date-time"},"meta":{"$ref":"#/components/schemas/MessageMeta"},"receiverTypes":{"description":"ReceiverTypes list of types of receivers for the message. It can be `to`, `cc` and `bcc` at the moment. Currently only use for inbound email platforms messages.\n","type":"array","items":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]}},"inbox":{"$ref":"#/components/schemas/InboxRef"}}},"Participant":{"type":"object","description":"A participant who can send and receive messages in the conversation","title":"ConversationParticipant","additionalProperties":false,"properties":{"id":{"type":"string","description":"Participant ID, the meaning of this field depends on `type`. If `type` is `user` then it's a user ID, if `type` is `contact` then it's a contact ID, if `type` is `accessKey` then it's the access key ID, and so on.\n"},"displayName":{"type":"string","description":"The participant's name."},"avatarUrl":{"type":"string","description":"An URL to the participant's avatar."},"contact":{"$ref":"#/components/schemas/ParticipantContact"},"type":{"$ref":"#/components/schemas/ParticipantType"},"status":{"type":"string","description":"Participant status in the conversation. `pending` means it's pending approval, `invited` means it's pending acceptance from the participant, and `active` means the participant can send and receive messages.\n","enum":["pending","invited","active"],"default":"active"}},"required":["id","type"]},"ParticipantContact":{"type":"object","description":"The participant's contact information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddress":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."}}},"ParticipantType":{"type":"string","description":"Participant type. The main ones are `user`, `contact`, and `agent`. `user` is a user belonging to your Bird workspace, `contact` is one of your customers, `agent` is a customer service agent, and the remaining types represent system participants.\n","enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"]},"DraftMessageMeta":{"type":"object","description":"Metadata for draft messages.","additionalProperties":false,"required":["creatorType"],"properties":{"creatorType":{"type":"string","description":"The type of creator of the draft message.","enum":["bot","user"]}}},"MessageRecipient":{"type":"object","description":"Participant who receives a message.","title":"MessageRecipient","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"Participant ID."},"type":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]},"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"platformAddress":{"type":"string"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."},"contactAnnotation":{"type":"object","description":"Contains the name of the contact","properties":{"name":{"nullable":true,"type":"string","description":"Contact name"}}},"isInbox":{"type":"boolean","description":"Indicates whether the recipient is the inbox."}}},"MessageStatus":{"type":"string","description":"Message status. The lifecycle order is `accepted`, `processing`, `sent`, and `delivered`.","enum":["accepted","processing","sent","sending_failed","delivered","delivery_failed","deleted"]},"InboxRef":{"type":"object","description":"A reference to an inbox.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of the inbox."},"identifier":{"$ref":"#/components/schemas/WorkspaceIdentifier"},"ownerId":{"type":"string","format":"uuid","description":"The ID of the owner of the inbox."},"ownerType":{"$ref":"#/components/schemas/InboxOwnerType"},"type":{"$ref":"#/components/schemas/InboxType"}},"required":["id","identifier","ownerId","ownerType","type"]},"WorkspaceIdentifier":{"type":"string","pattern":"^[a-z0-9._-]+$","description":"The identifier of the resource inside the workspace. Takes the form of the user component of an email address.\n"},"InboxOwnerType":{"type":"string","enum":["user","group"]},"InboxType":{"type":"string","enum":["personal","shared","support"]},"GenericError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"NotFoundError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ConflictError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ValidationError":{"title":"A validation error description","additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]}},"responses":{"forbidden":{"description":"User has no access to the requested resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}},"notFound":{"description":"The resource specified in the URL was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"duplicate":{"description":"The resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictError"}}}},"validationFailed":{"description":"The request body did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/conversations/{conversationId}/messages":{"post":{"summary":"Create message in conversation","operationId":"createConversationMessage","description":"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.\n","tags":["conversation_message"],"parameters":[{"$ref":"#/components/parameters/conversationIdOrNil"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessage"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/duplicate"},"422":{"$ref":"#/components/responses/validationFailed"}}}}}} ``` ## Examples ### Sending a simple message {% tabs %} {% tab title="Request" %} ```bash 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!" } } }' ``` {% endtab %} {% tab title="Response (201 - Created)" %} ```json { "id": "0c854061-6026-48c7-a2e8-bffb6458727b", "conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08", "reference": "", "sender": { "id": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c", "type": "accessKey", "status": "active", "displayName": "My first email key", "avatarUrl": "" }, "draft": false, "recipients": [ { "type": "to", "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04", "identifierKey": "emailaddress", "identifierValue": "some.customer@example.com", "platformAddress": "some.customer@example.com", "contactAnnotation": { "name": "John Doe" } } ], "status": "accepted", "source": "conversations", "body": { "type": "text", "text": { "text": "Hey, listen!" } }, "interactions": null, "createdAt": "2024-11-25T20:12:10.514Z", "updatedAt": "2024-11-25T20:12:10.514Z" } ``` {% endtab %} {% endtabs %} ### Sending a template message {% tabs %} {% tab title="Request" %} ```bash 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 }' ``` {% endtab %} {% tab title="Response (201 - Created)" %} ```json { "id": "cfd0877a-bc16-4e85-9f20-8996f2ebfa15", "conversationId": "907798f8-fd72-44d5-8042-fcc05c1bb570", "reference": "", "sender": { "id": "68b80b8d-8060-42df-bda3-73505a8fdb84", "type": "accessKey", "status": "active", "displayName": "My first email key", "avatarUrl": "" }, "draft": true, "recipients": [ { "type": "to", "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04", "identifierKey": "emailaddress", "identifierValue": "john.doe@bird.com", "platformAddress": "john.doe@bird.com", "contactAnnotation": { "name": "John Doe" } } ], "status": "accepted", "source": "conversations", "template": { "projectId": "5d9084b3-7cdb-4c87-bf7c-8871a1f21695", "version": "b33761d9-ece1-48e3-b542-b5bbf93bd8c3", "name": "", "locale": "en", "variables": null, "shortLinks": null, "parameters": [ { "type": "string", "key": "myVariable", "value": "yay" } ] }, "body": { "type": "html", "html": { "html": "
Hello, this is a test template with a variable: {{ myVariable | default: 'some default value' }}
", "metadata": { "subject": "Your email subject goes here." } } }, "interactions": null, "createdAt": "2024-12-02T13:22:45.736Z", "updatedAt": "2024-12-02T13:22:45.736Z" } ``` {% endtab %} {% endtabs %}