Attach or detach a label across many contacts

POST

/{phone_number_id}/contacts/bulk_label

const url = 'https://api.kirim.chat/v1/106540352242922/contacts/bulk_label';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"contact_ids":["example"],"label_id":"example","operation":"attach"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

• Production

Apply or remove a label from up to 1000 contacts in a single transaction. Contacts not owned by the path-scoped account are silently skipped and counted under skipped_cross_org.

Authorizations

• bearerAuth

Parameters

Path Parameters

phone_number_id

required

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

string

/^\d{6,20}$/

Example

106540352242922

Request Body

Media type application/json

object

contact_ids

required

Array<string>

>= 1 items <= 1000 items

label_id

required

string

/^lbl_[0-9A-HJKMNP-TV-Z]{26}$/

operation

required

string

Allowed values: attach detach

Responses

200

Bulk operation result

Media type application/json

object

data

required

object

applied

required

integer

skipped_cross_org

required

integer

skipped_team_mismatch

required

integer

request_id

required

string

Example ^generated

{
  "data": {
    "applied": 1,
    "skipped_cross_org": 1,
    "skipped_team_mismatch": 1
  },
  "request_id": "example"
}

400

Validation failure

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

401

Authentication failure

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

404

Resource not found

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

422

Semantic failure (e.g. idempotency key reuse)

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

429

Rate limit exceeded

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

500

Internal server error

Media type application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}