Update conversation message

Update a message

Update a draft conversation message. Sent messages cannot be updated. Setting draft to false causes the draft message to be sent.

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

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"

messageId*string (uuid)

The message ID

Example: "f303d128-0619-49ce-9e2a-669098d7d78b"

Body

application/json

draftnullable boolean

Whether the message is being drafted. Sent messages cannot be turned back into draft.

bodyMessageBody

statusnullable enum

Message status. The lifecycle order is accepted, processing, sent, and delivered.

acceptedprocessingsentsending_faileddelivereddelivery_failed

Response

200404422

OK

Body

application/json

id*string

Message ID.

Example: "aef328e7-6282-4268-a35b-4e5fd9033d2d"

conversationIdstring

Conversation ID.

Example: "0c63be07-3e97-42a3-900a-47e538032b73"

referencestring

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.

Example: "my-own-business-logic-id-12345"

sender*ConversationParticipant

A participant who can send and receive messages in the conversation

draft*boolean

Whether this message is a draft.

recipientsarray of MessageRecipient

Recipient list of this message.

status*Conversations_MessageStatus (enum)

Message status. The lifecycle order is accepted, processing, sent, and delivered.

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

source*enum

Whether the message was created by Bird's Conversations API or an external party.

Example: "conversations"

conversationsexternal

templatenullable Conversations_Template (object)

bodyMessageBody

reasonstring

Failure reason. Will be populated if the status is sending_failed or delivery_failed.

Example: "Insufficient credit"

interactionsnullable array of object

A list of interactions associated with the message.

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"

metaMessageMeta

Message metadata fields that might be populated depending on the channel being used.

receiverTypesarray of enum

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.

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404422

{
  "id": "aef328e7-6282-4268-a35b-4e5fd9033d2d",
  "conversationId": "0c63be07-3e97-42a3-900a-47e538032b73",
  "reference": "my-own-business-logic-id-12345",
  "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"
  },
  "draft": false,
  "recipients": [
    {
      "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
      "type": "to",
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddress": "text",
      "platformAddressSelector": "attributes.workEmail",
      "contactAnnotation": {
        "name": "John Doe"
      }
    }
  ],
  "status": "accepted",
  "source": "conversations",
  "template": {
    "name": "text",
    "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": false
      }
    ],
    "shortLinks": {
      "enabled": false,
      "domain": "text"
    },
    "variables": {
      "default": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "whatsapp": {
          "previewUrl": false
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 0,
                "productId": "text",
                "emojiId": "text",
                "length": 0
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "reason": "Insufficient credit",
  "interactions": [
    {
      "id": "29f3aab3-ecd7-4a8c-92d3-c3366cfedd79",
      "type": "read",
      "createdAt": "2024-01-01T00:00:00.123Z",
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        }
      }
    }
  ],
  "createdAt": "2024-01-01T00:00:00.123Z",
  "updatedAt": "2024-01-01T00:00:00.123Z",
  "meta": {
    "email": {
      "subject": "text",
      "from": {
        "username": "john.doe",
        "displayName": "John Doe"
      }
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "sourceId": "120211000000000000",
        "sourceUrl": "https://instagram.com/p/EXAMPLEID",
        "mediaType": "IMAGE",
        "mediaUrl": "https://cdninstagram.com/v/example",
        "caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
        "username": "DreamCosmetics",
        "timestamp": "2024-11-28T12:00:00.000Z",
        "trackingId": "text"
      }
    }
  },
  "receiverTypes": [
    "to"
  ]
}

Examples

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages/884d1fa0-9335-484f-b6ca-96fb7e2c39f9" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "draft": false,
  "body": {
    "type": "text",
    "text": {
      "text": "Hey, listen!"
    }
  }
}'

Response (200 - OK)

{
  "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": "[e-mail]",
      "platformAddress": "[e-mail]",
      "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"
}