Conversations

Attach a label to a conversation

POST

/{phone_number_id}/conversations/{id}/labels

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.kirimdev.com/v1/106540352242922/conversations/cnv_01HXYZABCDEFGHJKMNPQRSTVWX/labels"

  payload := strings.NewReader("{ \"label_id\": \"example\" }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Idempotency-Key", "order-20260910-0001")
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

const url = 'https://api.kirimdev.com/v1/106540352242922/conversations/cnv_01HXYZABCDEFGHJKMNPQRSTVWX/labels';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'order-20260910-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"label_id":"example"}'
};

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

use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.kirimdev.com/v1/106540352242922/conversations/cnv_01HXYZABCDEFGHJKMNPQRSTVWX/labels";

    let payload = json!({"label_id": "example"});

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Idempotency-Key", "order-20260910-0001".parse().unwrap());
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request POST \
  --url https://api.kirimdev.com/v1/106540352242922/conversations/cnv_01HXYZABCDEFGHJKMNPQRSTVWX/labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-20260910-0001' \
  --data '{ "label_id": "example" }'

Attach an organization label to an inbox conversation. The label and conversation must belong to compatible team scope; duplicate attachment is idempotent.

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

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).

required

Public Kirimdev conversation ID.

string

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

Example

cnv_01HXYZABCDEFGHJKMNPQRSTVWX

Public Kirimdev conversation ID.

Header Parameters

Idempotency-Key

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

string

Example

order-20260910-0001

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

Request Body

application/json

object

label_id

required

string

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

Example ^generated

{
  "label_id": "example"
}

Responses

200

Attached

application/json

object

data

required

The requested resource.

object

conversation_id

required

string

label_id

required

string

attached

required

boolean

request_id

required

Unique request identifier to include when contacting support.

string

Example

{
  "data": {
    "attached": true
  },
  "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

400

Validation failure

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

A field value is invalid.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field_value",
    "message": "A field value is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

401

Authentication failure

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

The provided API key is invalid.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

404

Resource not found

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Resource not found.

{
  "error": {
    "type": "not_found",
    "code": "resource_not_found",
    "message": "Resource not found.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

409

Conflict (e.g. template already exists, webhook subscription disabled, setup link inactive)

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

An identical request is still being processed. Retry later.

{
  "error": {
    "type": "conflict",
    "code": "idempotency_in_progress",
    "message": "An identical request is still being processed. Retry later.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

422

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

The WhatsApp number is not verified for this organization.

{
  "error": {
    "type": "invalid_request_error",
    "code": "whatsapp_number_not_verified",
    "message": "The WhatsApp number is not verified for this organization.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

429

Rate limit exceeded

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

Rate limit exceeded.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

500

Internal server error

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error

code

required

string

message

required

Human-readable explanation of the error.

string

param

Request field associated with the error, when applicable.

string

request_id

required

Unique request identifier to include when contacting support.

string

Examples

default

An unexpected error occurred.

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

Attach a label to a conversation

Authorizations

Parameters

Path Parameters

Example

Example

Header Parameters

Example

Request Body

Example generated

Responses

200

Example

400

Examples

401

Examples

404

Examples

409

Examples

422

Examples

429

Examples

500

Examples

Example ^generated