# Create conversation

## Create conversation

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

```json
{"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[{"name":"conversation","description":"Conversations are a collection of messages between two or more participants."}],"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"}},"schemas":{"CreateConversation":{"allOf":[{"type":"object","description":"A conversation.","additionalProperties":true,"properties":{"name":{"type":"string","description":"Name of the conversation. If it's an email channel, this will correspond to the email subject."},"description":{"type":"string","description":"Conversation description."},"style":{"$ref":"#/components/schemas/ConversationStyle"},"visibility":{"$ref":"#/components/schemas/ConversationVisibility"},"accessibility":{"$ref":"#/components/schemas/ConversationAccessibility"},"participants":{"type":"array","description":"A list of up to 5 conversation participants.","items":{"$ref":"#/components/schemas/ParticipantRef"}},"initiatingParticipant":{"$ref":"#/components/schemas/ParticipantRef","description":"The participant who initiated the conversation. When both initiatingParticipant and \ninitialMessage are provided, the initial message sender takes precedence.\n"},"channelId":{"type":"string","description":"Channel ID.","format":"uuid","minLength":1},"initialMessage":{"$ref":"#/components/schemas/CreateInitialMessage"},"attributes":{"nullable":true,"type":"object","description":"A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.\n","additionalProperties":true},"resource":{"$ref":"#/components/schemas/Resource"}},"required":["name"]},{"anyOf":[{"type":"object","properties":{"channelId":{}},"required":["channelId"]},{"type":"object","properties":{"resource":{}},"required":["resource"]}]}]},"ConversationStyle":{"type":"string","description":"The style of the conversation. - `default`: The conversation style is dictated by the underlying platform. Participants will be a mix of user and contact participants. - `directMessage`: The conversation is a direct conversation between user participants. Participants will be of user type. - `chatChannel`: The conversation is a chat channel conversation. Participants will be of user type. - `personalInbox`: The conversation is in the personal inbox for a user participant. Participants will be the owning user, and one or more personal contact participants. - `resource`: The conversation consists of comments on a resource. Participants will be of user type and `resource` will be set.\n","enum":["default","directMessage","chatChannel","personalInbox","resource","groupInbox"],"default":"default"},"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"},"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"]}}}]},"CreateInitialMessage":{"nullable":true,"type":"object","oneOf":[{"type":"object","description":"Initial message that will initiate the conversation.","title":"MessageCreateWithBody","additionalProperties":false,"required":["body"],"properties":{"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/MessageSender"},"recipients":{"$ref":"#/components/schemas/CreateMessageRecipients"},"body":{"$ref":"#/components/schemas/Body"},"draft":{"type":"boolean","description":"Whether this message is a draft.","default":false}}},{"type":"object","description":"Initial message that will initiate the conversation.","title":"MessageCreateWithTemplate","additionalProperties":false,"required":["template"],"properties":{"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/MessageSender"},"recipients":{"$ref":"#/components/schemas/CreateMessageRecipients"},"template":{"$ref":"#/components/schemas/Template"},"draft":{"type":"boolean","description":"Whether this message is a draft.","default":false}}},{"enum":[null]}]},"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."}}},"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"]}}}}},"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."}}}}},"Resource":{"type":"object","description":"Resource reference","additionalProperties":false,"nullable":true,"properties":{"type":{"type":"string","description":"The type of referenced resource","enum":["task","task-conversation","reimbursement","expense","sales-lead","sales-opportunity","sales-account","project"]},"id":{"type":"string","format":"uuid","description":"The ID of the referenced resource."}}},"Conversation":{"type":"object","title":"Conversation","description":"A conversation object.","required":["id","name","status","visibility","accessibility","channelId","featuredParticipants","activeParticipantCount","createdAt","updatedAt","platformStyle"],"properties":{"id":{"type":"string","description":"Conversation ID."},"name":{"type":"string","description":"Name of the conversation. If it's an email channel, this will correspond to the email subject."},"description":{"type":"string","description":"Conversation description."},"status":{"$ref":"#/components/schemas/ConversationStatus"},"visibility":{"$ref":"#/components/schemas/ConversationVisibility"},"accessibility":{"$ref":"#/components/schemas/ConversationAccessibility"},"style":{"$ref":"#/components/schemas/ConversationStyle"},"featuredParticipants":{"type":"array","description":"A list of up to 5 conversation participants.","items":{"$ref":"#/components/schemas/Participant"},"minItems":0,"maxItems":5},"initiatingParticipant":{"$ref":"#/components/schemas/Participant"},"activeParticipantCount":{"type":"integer","description":"Number of active participants.","minimum":0},"pendingParticipantCount":{"type":"integer","description":"Number of participants who have requested to join the conversation with pending approval.","minimum":0},"channelId":{"type":"string","description":"Channel ID.","format":"uuid","minLength":1},"lastMessage":{"$ref":"#/components/schemas/LastMessage"},"lastMessageIncomingAt":{"type":"string","description":"Timestamp of the last incoming message in RFC3339 format.","format":"date-time","nullable":true},"lastMessageOutgoingAt":{"type":"string","description":"Timestamp of the last outgoing message in RFC3339 format.","format":"date-time","nullable":true},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"updatedAt":{"type":"string","description":"Update timestamp formatted as RFC3339.","format":"date-time"},"platformStyle":{"type":"string","description":"The communication style of the platform.\n`email` represents an email channel;\n`direct` represents a 1:1 conversation, most channels will fall in this category, like WhatsApp and RCS;\n`direct-multiple` represents a channel that supports multiple conversations per contact, e.g. Chat;\n`direct-threaded` represents a threaded communication channel, e.g. Instagram Comments.\n","enum":["direct","email","direct-multiple","direct-threaded","group-multiple"]},"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","additionalProperties":true},"summary":{"type":"string","description":"Summary of the conversation."},"referral":{"$ref":"#/components/schemas/Referral"},"likelySpam":{"type":"boolean","description":"Whether this conversation was flagged as spam. Only present when anti-spam is enabled in the workspace settings."},"likelySpamReason":{"type":"string","description":"Reason for being flagged as spam."},"resource":{"$ref":"#/components/schemas/Resource"},"hasDraft":{"type":"boolean","description":"Indicates if the conversation contains at least one draft message."}}},"ConversationStatus":{"type":"string","description":"Status of the conversation. Attempting to send messages in closed conversations results in an error.\n","enum":["active","closed","deleted"],"default":"active"},"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"]},"LastMessage":{"type":"object","description":"Last message sent in this conversation.","additionalProperties":false,"required":["id","status","preview","createdAt"],"properties":{"id":{"type":"string","description":"Message ID.","format":"uuid","minLength":1},"type":{"$ref":"#/components/schemas/BodyTypes"},"preview":{"$ref":"#/components/schemas/textPreview"},"status":{"$ref":"#/components/schemas/MessageStatus"},"sender":{"nullable":true,"$ref":"#/components/schemas/Participant"},"recipients":{"type":"array","description":"Recipients of the last message.","nullable":true,"items":{"$ref":"#/components/schemas/MessageRecipient"}},"draft":{"type":"boolean","description":"Whether this message is a draft."},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"}}},"textPreview":{"type":"object","description":"A preview of the text sent in the last message.","required":["text"],"properties":{"text":{"type":"string","description":"The text sent in the last message."}}},"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"]},"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."}}},"Referral":{"type":"object","description":"This represents a social media post or an ad that was referenced when starting the conversation.","additionalProperties":false,"properties":{"sourceUrl":{"type":"string","description":"The URL of the social media post or ad."},"sourceId":{"type":"string","description":"The ID of the social media post or ad."},"sourceType":{"type":"string","description":"The type of referral, can be `FEED` or `AD`."},"mediaUrl":{"type":"string","description":"Link to the media associated with the referral post or ad."},"mediaType":{"type":"string","description":"Type of media used in the post or ad."},"caption":{"type":"string","description":"Caption associated with the referral post or ad."},"title":{"type":"string","description":"Title of the referral post or ad."},"text":{"type":"string","description":"Text content of 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"}}},"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":{"post":{"summary":"Create conversation","operationId":"createConversation","description":"Create a new conversation for a workspace, optionally specifying an initial message to be sent.\n","tags":["conversation"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversation"}}}},"responses":{"201":{"description":"The conversation is created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/duplicate"},"422":{"$ref":"#/components/responses/validationFailed"}}}}}}
```

## Examples

### Starting a conversation with a simple message

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "name": "Email Subject",
  "channelId": "25431165-c486-4a94-94f6-b3633c9af905",
  "participants": [
    {
      "type": "contact",
      "identifierKey": "emailaddress",
      "identifierValue": "john.doe@bird.com"
    }
  ],
  "initialMessage": {
    "body": {
      "type": "text",
      "text": {
        "text": "Hey, listen!"
      }
    },
    "recipients": [
      {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "type": "to"
      }
    ]
  },
  "attributes": {
    "my-custom-attribute": "123"
  }
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

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

{% endtab %}
{% endtabs %}

### Starting a conversation with an email template message

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "name": "Email Subject",
  "channelId": "25431165-c486-4a94-94f6-b3633c9af905",
  "participants": [
    {
      "type": "contact",
      "identifierKey": "emailaddress",
      "identifierValue": "john.doe@bird.com"
    }
  ],
  "initialMessage": {
    "template": {
      "projectId": "5d9084b3-7cdb-4c87-bf7c-8871a1f21695",
      "version": "b33761d9-ece1-48e3-b542-b5bbf93bd8c3",
      "locale": "en",
      "parameters": [
        {
          "type": "string",
          "key": "myVariable",
          "value": "yay"
        }
      ]
    },
    "recipients": [
      {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "type": "to"
      }
    ]
  },
  "attributes": {
    "my-custom-attribute": "123"
  }
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

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

{% endtab %}
{% endtabs %}

### Starting a conversation with a WhatsApp template message

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "name": "Ticket name",
  "channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
  "participants": [
    {
      "type": "contact",
      "identifierKey": "phonenumber",
      "identifierValue": "+31612345678"
    }
  ],
  "initialMessage": {
    "template": {
      "projectId": "4720942c-9bde-4934-ab77-f600743894a1",
      "version": "5c0e4db5-20f2-4224-86f4-fce052997608",
      "locale": "en",
      "parameters": [
        {
          "type": "string",
          "key": "age",
          "value": "20"
        }
      ]
    },
    "recipients": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+31612345678",
        "type": "to"
      }
    ]
  },
  "attributes": {
    "my-custom-attribute": "123"
  }
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

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

{% endtab %}
{% endtabs %}