Update conversation

Update conversation

patch

Update a conversation's properties

Authorizations

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdstring · uuidrequired

The workspace ID

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

conversationIdstring · uuidrequired

The conversation ID

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

Body

namestring | nullableoptional

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

Example: Re: Your refund request

descriptionstring | nullableoptional

statusstring · enum · default: "active"optional

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

Options: active, closed, spam, archived, deleted

visibilitystring · enum · default: "public"optional

Whether the conversation is public or private.

Options: public, private, direct, group

accessibilitystring · enum · default: "open"optional

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

Options: open, invite-only, request-to-join, private

attributesobjectoptional

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

Example: {"myCustomField":"abc"}

resourceobject | nullableoptional

Resource reference

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Re: Your refund request",
    "description": "text",
    "status": "active",
    "visibility": "public",
    "accessibility": "open",
    "attributes": {
      "myCustomField": "abc"
    },
    "resource": {
      "type": "task",
      "id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }'

200

404

409

422

200

{
  "id": "299227f5-1c61-4341-ad50-efed5c048998",
  "name": "Re: Your refund request",
  "description": "Refund request ticket",
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "style": "default",
  "featuredParticipants": [
    {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "displayName": "John Doe",
      "avatarUrl": "https://example.bird.com/avatar-url",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "[e-mail]",
        "platformAddress": "[e-mail]",
        "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": "[e-mail]",
      "platformAddress": "[e-mail]",
      "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": "[e-mail]",
        "platformAddress": "[e-mail]",
        "platformAddressSelector": "attributes.workEmail"
      },
      "type": "user",
      "status": "pending"
    },
    "recipients": [
      {
        "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
        "type": "to",
        "identifierKey": "emailaddress",
        "identifierValue": "[e-mail]",
        "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": true,
  "likelySpamReason": "advertisement",
  "resource": {
    "type": "task",
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

The conversation was updated

Examples

Request

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

Response (200 - OK)

{
  "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": "[e-mail]",
        "platformAddress": "[e-mail]"
      }
    },
    {
      "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": "[e-mail]",
        "platformAddress": "[e-mail]"
      }
    }
  ],
  "activeParticipantCount": 2,
  "pendingParticipantCount": 1,
  "initiatingParticipant": {
    "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
    "type": "contact",
    "status": "active",
    "displayName": "John Doe",
    "avatarUrl": "",
    "contact": {
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddress": "[e-mail]"
    }
  },
  "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": "[e-mail]",
        "platformAddress": "[e-mail]",
        "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"
  }
}