Update a WhatsApp conversation

PATCH

/v1/whatsapp/conversations/{conversation_id}

// labels replaces the whole set, so send every label to keep.
const conversation = await bird.whatsapp.conversations.update("wacv_01krdgeqcxet5s7t44vh8rt9mg", {
  assigned_to: "usr_01krdgeqcxet5s7t44vh8rt9mg",
  labels: ["billing", "vip"],
  inbox_status: "resolved",
});
console.log(conversation.inbox_status);

# labels replaces the whole set, so send every label to keep.
conversation = client.whatsapp.conversations.update(
    "wacv_01krdgeqcxet5s7t44vh8rt9mg",
    assigned_to="usr_01krdgeqcxet5s7t44vh8rt9mg",
    labels=["billing", "vip"],
    inbox_status="resolved",
)
print(conversation.inbox_status)

// Labels replaces the whole set, so send every label to keep.
conversation, err := client.Whatsapp.Conversations.Update(context.Background(), "wacv_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappConversationsUpdateParams{
	AssignedTo:  bird.Value("usr_01krdgeqcxet5s7t44vh8rt9mg"),
	Labels:      []string{"billing", "vip"},
	InboxStatus: bird.Ptr(bird.ConversationInboxStatus("resolved")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(conversation.InboxStatus)

// labels replaces the whole set, so send every label to keep.
$conversation = $bird->whatsapp->conversations->update(
    'wacv_01krdgeqcxet5s7t44vh8rt9mg',
    (new WhatsAppConversationUpdateRequest())
        ->setAssignedTo('usr_01krdgeqcxet5s7t44vh8rt9mg')
        ->setLabels(['billing', 'vip'])
        ->setInboxStatus('resolved'),
);
echo $conversation->getInboxStatus();

bird whatsapp conversations update <conversation-id> --labels billing

curl -X PATCH "https://us1.platform.bird.com/v1/whatsapp/conversations/{conversation_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      "billing"
    ]
  }'

Response200

{
  "id": "wacv_01krdgeqcxet5s7t44vh8rt9mg",
  "business_phone_number": "+15550001234",
  "recipient": {
    "bsuid": "US.13491208655302741918",
    "phone_number": "+15550001111",
    "display_name": "Jamie Rivera",
    "username": "jamierivera"
  },
  "inbox_status": "open",
  "control": "bird",
  "assigned_to": "usr_01krdgeqcxet5s7t44vh8rt9mg",
  "service_window": {
    "status": "open",
    "ends_at": "2026-09-23T10:35:00Z"
  },
  "last_message": {
    "id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
    "direction": "outbound"
  },
  "labels": [
    "billing",
    "vip"
  ]
}

Updates assignment, inbox status, labels, or shared workspace read state. Every field is optional and an omitted one is left unchanged.

assigned_to takes a user ID, me for the user making the request, or null to unassign. The user must be a member of this workspace. me needs a request made as a user: an API key has no user, so passing me with one returns a 422.

labels replaces the conversation's labels with the set you send, so include every label you want to keep. Pass an empty array to clear them.

Pass read with a date-time cutoff for message created_at to acknowledge received inbound messages at or before it in the workspace inbox. Messages sharing the timestamp are included together; later arrivals remain unread. This does not send the customer a WhatsApp read receipt.

Labels are yours alone: Bird sets none of its own, and changing them does not mark the conversation read or unread.

Set inbox_status to resolved to finish the inbox work, or open to reopen it. New inbound messages reopen resolved conversations. Inbox status does not change read state or the customer-service window.

Control is not changed here. Moving a conversation between the agent and your application needs WhatsApp's agreement and can be refused, so you take and release control in the dashboard inbox.

Parameters

conversation_idstring

Conversation identifier. Starts with wacv_.

Request Payload

assigned_to

nullable string

User to assign this conversation to. Pass a workspace member's user ID, me for the signed-in user, or null to unassign it. An API key cannot use me and receives a 422 response.

inbox_status

string

Whether the conversation needs attention in the workspace inbox. Set it to resolved when the work is finished. A new inbound message reopens the same conversation. Changing inbox status preserves message history and does not change the channel's permission to send messages or mark messages read.

Possible values: open, resolved

labels

array of string

Labels chosen by your workspace. On update, this replaces the full set; pass an empty array to clear every label. Labels do not change read state or inbox status.

Each label must contain 1 to 64 characters, with no commas, control characters, or leading or trailing whitespace. Duplicate labels are rejected. The names all, archived, assigned, closed, deleted, draft, drafts, flagged, important, inbox, junk, muted, none, open, pinned, read, snoozed, spam, starred, trash, and unread are reserved in every casing.

read

string

Mark received inbound messages with created_at at or before this timestamp as read in the shared workspace inbox. Messages sharing the timestamp are included together. Later arrivals remain unread until another read update. This does not send a read receipt to the customer or change inbox status. Omit to leave read state unchanged.

Response Payload

id

string

required

Conversation ID.

business_phone_number

nullable string

required

Your WhatsApp business phone number this conversation runs on, in E.164 format. It stays the same when you remove the number and connect it again. Null when Bird holds no phone number for it.

recipient

object

required

The other side of the conversation: the contact, or the group it takes place in. A group conversation carries group_id and null contact identity fields.

Show child attributes

recipient.bsuid

nullable string

required

Meta's business-scoped user ID for the contact, or null when unknown.

recipient.phone_number

nullable string

required

Contact phone number in E.164 format, or null when unknown.

recipient.display_name

nullable string

required

Display name from the contact's WhatsApp profile, or null when none has been recorded.

recipient.username

nullable string

required

Contact's WhatsApp username without a leading @, or null when none has been recorded. Messages cannot be addressed by username.

recipient.group_id

string

Group this conversation belongs to. Omitted for a conversation with one contact.

inbox_status

string

required

Possible values: open, resolved

control

string

required

Who answers this conversation right now. You take and release control in the dashboard inbox.

Possible values (may grow over time): bird, meta_business_agent

assigned_to

nullable string

required

The user this conversation is assigned to. Null when unassigned. Assignment is not rechecked against workspace membership on read, so it can still name a user whose access was removed.

service_window

nullable object

required

Customer-service window for a contact. Null for group conversations.

Show child attributes

last_message

nullable object

required

A pointer to the most recent message in this conversation. It names the message; read its content through the conversation's message list. Null when the conversation has no message yet.

Show child attributes

unread_count

integer

required

Number of inbound messages the workspace has not acknowledged. Shared across the workspace. Sending a reply does not mark messages read.

labels

array of string

required

Workspace labels on this conversation. Labels do not change read state or inbox status.

created_at

string

required

When Bird opened this conversation.

updated_at

string

required

When this conversation last changed.

Continue with the documentation, guides and examples for this topic.

Get an implementation brief

// labels replaces the whole set, so send every label to keep.
const conversation = await bird.whatsapp.conversations.update("wacv_01krdgeqcxet5s7t44vh8rt9mg", {
  assigned_to: "usr_01krdgeqcxet5s7t44vh8rt9mg",
  labels: ["billing", "vip"],
  inbox_status: "resolved",
});
console.log(conversation.inbox_status);

# labels replaces the whole set, so send every label to keep.
conversation = client.whatsapp.conversations.update(
    "wacv_01krdgeqcxet5s7t44vh8rt9mg",
    assigned_to="usr_01krdgeqcxet5s7t44vh8rt9mg",
    labels=["billing", "vip"],
    inbox_status="resolved",
)
print(conversation.inbox_status)

// Labels replaces the whole set, so send every label to keep.
conversation, err := client.Whatsapp.Conversations.Update(context.Background(), "wacv_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappConversationsUpdateParams{
	AssignedTo:  bird.Value("usr_01krdgeqcxet5s7t44vh8rt9mg"),
	Labels:      []string{"billing", "vip"},
	InboxStatus: bird.Ptr(bird.ConversationInboxStatus("resolved")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(conversation.InboxStatus)

// labels replaces the whole set, so send every label to keep.
$conversation = $bird->whatsapp->conversations->update(
    'wacv_01krdgeqcxet5s7t44vh8rt9mg',
    (new WhatsAppConversationUpdateRequest())
        ->setAssignedTo('usr_01krdgeqcxet5s7t44vh8rt9mg')
        ->setLabels(['billing', 'vip'])
        ->setInboxStatus('resolved'),
);
echo $conversation->getInboxStatus();

bird whatsapp conversations update <conversation-id> --labels billing

curl -X PATCH "https://us1.platform.bird.com/v1/whatsapp/conversations/{conversation_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      "billing"
    ]
  }'

Response200

{
  "id": "wacv_01krdgeqcxet5s7t44vh8rt9mg",
  "business_phone_number": "+15550001234",
  "recipient": {
    "bsuid": "US.13491208655302741918",
    "phone_number": "+15550001111",
    "display_name": "Jamie Rivera",
    "username": "jamierivera"
  },
  "inbox_status": "open",
  "control": "bird",
  "assigned_to": "usr_01krdgeqcxet5s7t44vh8rt9mg",
  "service_window": {
    "status": "open",
    "ends_at": "2026-09-23T10:35:00Z"
  },
  "last_message": {
    "id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
    "direction": "outbound"
  },
  "labels": [
    "billing",
    "vip"
  ]
}

Update a WhatsApp conversation

Parameters

Request Payload

Response Payload

Related resources