No-code docs
Resources

Create conversation

Create conversation

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

post

/workspaces/{workspaceId}/conversations

Authorizations
Path parameters
workspaceIdstring · uuidrequired

The workspace ID

Example: b4e02c85-c6d2-4b15-8885-e09671799c61
Body
namestringrequired

Name of the conversation. If it's an email channel, this will correspond to the email subject.

Example: Re: Your refund request
descriptionstring

Conversation description.

Example: Refund request ticket
channelIdstring · uuid · min: 1

Channel ID.

Example: ab651378-579a-4491-abe6-eec97d4c0fa3
initialMessageobject | nullable
resourceobject | nullable

Resource reference

visibilitystring · enum · default: public

Whether the conversation is public or private.

Options: public, private
accessibilitystring · enum · default: open

Indicates the access level for new participants to join the conversation.

Options: open, invite-only, request-to-join
participantsobject[]

A list of up to 5 conversation participants.

attributesobject | nullable

A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.

Example: {"myCustomField":"abc"}
Other propertiesany
any of
Responses
curl -L \
  --request POST \
  --url 'https://api.bird.com/workspaces/{workspaceId}/conversations' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Re: Your refund request","description":"Refund request ticket","channelId":null,"initialMessage":{"reference":"my-own-business-logic-id-12345","sender":{"name":"Bird Support","email":"example@bird.com"},"recipients":[{"identifierKey":"emailaddress","identifierValue":"example@bird.com","platformAddressSelector":"attributes.workEmail","type":"to"}],"body":{"type":"text","text":{"text":"text","actions":[{"type":"link","link":{"text":"text"}}],"attachments":[{"mediaUrl":"https://example.com","filename":"text"}],"metadata":{"telegram":{"parseMode":"Markdown"},"headers":{},"whatsapp":{},"line":{"emoji":{"items":[{"index":1,"productId":"text","emojiId":"text"}]}}}}}},"resource":{"type":"task"},"visibility":"public","accessibility":"open","participants":[{"id":"986c5b08-3ec7-424a-a380-f3b41dc02746","type":"user"}],"attributes":{"myCustomField":"abc"},"ANY_ADDITIONAL_PROPERTY":"anything"}'
{
  "id": "299227f5-1c61-4341-ad50-efed5c048998",
  "name": "Re: Your refund request",
  "description": "Refund request ticket",
  "initiatingParticipant": {
    "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
    "displayName": "John Doe",
    "avatarUrl": "https://example.bird.com/avatar-url",
    "contact": {
      "identifierKey": "emailaddress",
      "identifierValue": "example@bird.com",
      "platformAddress": "example@bird.com",
      "platformAddressSelector": "attributes.workEmail"
    },
    "type": "user",
    "status": "active"
  },
  "activeParticipantCount": 2,
  "pendingParticipantCount": 1,
  "channelId": "ab651378-579a-4491-abe6-eec97d4c0fa3",
  "lastMessage": {
    "id": "69e97125-ddd4-4042-9d58-8350e806e1de",
    "type": "text",
    "preview": {
      "text": "Thank you for reaching out, could you please inform your account number?"
    },
    "status": "accepted",
    "sender": {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "displayName": "John Doe",
      "avatarUrl": "https://example.bird.com/avatar-url",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "example@bird.com",
        "platformAddress": "example@bird.com",
        "platformAddressSelector": "attributes.workEmail"
      },
      "type": "user",
      "status": "active"
    },
    "createdAt": "2024-01-01T00:00:00.123Z",
    "recipients": [
      {
        "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
        "identifierKey": "emailaddress",
        "identifierValue": "example@bird.com",
        "platformAddress": "text",
        "platformAddressSelector": "attributes.workEmail",
        "type": "to",
        "contactAnnotation": {
          "name": "John Doe"
        }
      }
    ]
  },
  "createdAt": "2024-01-01T00:00:00.123Z",
  "updatedAt": "2024-01-01T00:00:00.123Z",
  "referral": {
    "sourceUrl": "https://instagram.com/p/EXAMPLEID",
    "sourceId": "120211000000000000",
    "sourceType": "AD",
    "mediaUrl": "https://cdninstagram.com/v/example",
    "mediaType": "IMAGE",
    "caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
    "title": "Dream Summer Days Daily SPF",
    "text": "Crafted with broad-spectrum SPF 50+ protection, Dream Summer Days Daily SPF offers reliable defense against both UVA and UVB rays",
    "username": "DreamCosmetics",
    "timestamp": "2024-11-28T12:00:00.000Z"
  },
  "likelySpam": true,
  "likelySpamReason": "advertisement",
  "resource": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "task"
  },
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "platformStyle": "direct",
  "featuredParticipants": [
    {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "displayName": "John Doe",
      "avatarUrl": "https://example.bird.com/avatar-url",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "example@bird.com",
        "platformAddress": "example@bird.com",
        "platformAddressSelector": "attributes.workEmail"
      },
      "type": "user",
      "status": "active"
    }
  ],
  "attributes": {
    "myCustomField": "abc"
  }
}

The conversation is created

Examples

Starting a conversation with a simple message

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

Starting a conversation with an email template message

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

Starting a conversation with a WhatsApp template message

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"
  }
}'

Last updated

Was this helpful?