Update conversation

Update a conversation's properties

PATCHhttps://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}

Path parameters

workspaceId*string (uuid)

The workspace ID

Example: "b4e02c85-c6d2-4b15-8885-e09671799c61"

conversationId*string (uuid)

The conversation ID

Example: "67e4d358-ca94-421e-98b7-448860df9d33"

Body

namenullable string

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

Example: "Re: Your refund request"

descriptionnullable string

statusnullable enum

Status of the conversation.

active

visibilitynullable enum

Whether the conversation is public or private.

publicprivate

accessibilitynullable enum

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

openinvite-onlyrequest-to-join

attributesobject

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

Response

The conversation was updated

Body

id*string

Conversation ID.

Example: "299227f5-1c61-4341-ad50-efed5c048998"

name*string

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"

status*enum

Status of the conversation. Attempting to send messages in closed conversations results in an error.

activeclosed

visibility*enum

Whether the conversation is public or private.

publicprivate

accessibility*enum

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

openinvite-onlyrequest-to-join

featuredParticipants*array of ConversationParticipant

A list of up to 5 conversation participants.

initiatingParticipantConversationParticipant

A participant who can send and receive messages in the conversation

activeParticipantCount*integer

Number of active participants.

Example: 2

pendingParticipantCountinteger

Number of participants who have requested to join the conversation with pending approval.

Example: 1

channelId*string (uuid)

Channel ID.

Example: "ab651378-579a-4491-abe6-eec97d4c0fa3"

lastMessageConversations_LastMessage (object)

Last message sent in this conversation.

createdAt*string (date-time)

Creation timestamp formatted as RFC3339.

Example: "2024-01-01T00:00:00.123Z"

updatedAt*string (date-time)

Update timestamp formatted as RFC3339.

Example: "2024-01-01T00:00:00.123Z"

platformStyle*enum

The communication style of the platform. email represents an email channel; direct represents a 1:1 conversation, most channels will fall in this category, like WhatsApp and RCS; direct-multiple represents a channel that supports multiple conversations per contact, e.g. Chat; direct-threaded represents a threaded communication channel, e.g. Instagram Comments.

directemaildirect-multiple

attributesobject

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

referralConversations_Referral (object)

This represents a social media post or an ad that was referenced when starting the conversation.

likelySpamboolean

Whether this conversation was flagged as spam. Only present when anti-spam is enabled in the workspace settings.

likelySpamReasonstring

Reason for being flagged as spam.

Example: "advertisement"

Request

Response

Examples

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/907798f8-fd72-44d5-8042-fcc05c1bb570" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "name": "new name",
  "description": "description",
  "visibility": "private",
  "attributes": {
    "my-attribute": "123"
  }
}'

{
  "id": "907798f8-fd72-44d5-8042-fcc05c1bb570",
  "name": "new name",
  "description": "description",
  "status": "active",
  "visibility": "private",
  "accessibility": "invite-only",
  "featuredParticipants": [
    {
      "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"
      }
    },
    {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    {
      "id": "3954d22c-96f7-4bc3-817b-67b4d903ed90",
      "type": "contact",
      "status": "active",
      "displayName": "",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com"
      }
    }
  ],
  "activeParticipantCount": 2,
  "pendingParticipantCount": 1,
  "initiatingParticipant": {
    "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"
    }
  },
  "channelId": "cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f",
  "lastMessage": {
    "id": "d578f436-b3b7-49e6-95c2-24b77bb4e7ce",
    "type": "text",
    "preview": {
      "text": "Hey, listen!"
    },
    "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": "delivered",
    "sender": {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    "createdAt": "2024-11-29T13:22:22.875Z"
  },
  "createdAt": "2024-11-25T19:31:47.264Z",
  "updatedAt": "2024-11-29T15:37:20.534Z",
  "platformStyle": "email",
  "attributes": {
    "my-attribute": "123"
  }
}

Last updated 21 days ago

{ "id": "299227f5-1c61-4341-ad50-efed5c048998", "name": "Re: Your refund request", "description": "Refund request ticket", "status": "active", "visibility": "public", "accessibility": "open", "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": "pending" } ], "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": "pending" }, "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": "pending" }, "recipients": [ { "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf", "type": "to", "identifierKey": "emailaddress", "identifierValue": "example@bird.com", "platformAddress": "text", "platformAddressSelector": "attributes.workEmail", "contactAnnotation": { "name": "John Doe" } } ], "createdAt": "2024-01-01T00:00:00.123Z" }, "createdAt": "2024-01-01T00:00:00.123Z", "updatedAt": "2024-01-01T00:00:00.123Z", "platformStyle": "direct", "attributes": { "myCustomField": "abc" }, "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": false, "likelySpamReason": "advertisement" }