Skip to content
kirim.dev
Messages

Send a WhatsApp message or mark inbound as read

POST
/{phone_number_id}/messages
 
const url = 'https://api.kirim.chat/v1/106540352242922/messages';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"messaging_product":"whatsapp","recipient_type":"individual","to":"example","type":"text","text":{"body":"example","preview_url":true}}'
};


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

Meta-style messages endpoint. Two operations share the same path, distinguished by the request body:

Outbound send — body has a type field (text, image, document, video, audio, template, interactive). Body shape mirrors the Meta WhatsApp Cloud API; media variants accept either link (hosted URL) or id (Meta uploaded media). The sender is the WhatsApp account identified by phone_number_id in the URL path; there is no from field in the body. Pass Idempotency-Key to safely retry on network failure.

Read receipt — body has status: "read" + message_id (the inbound wamid from your webhook). Sends a read receipt back to the sender so the double-tick turns blue on their phone. Optional typing_indicator: { type: "text" } shows a typing bubble alongside the receipt; Meta auto-dismisses after ~25 seconds or on first outbound message.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “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

Header Parameters

Section titled “Header Parameters ”
idempotency-key

Optional idempotency token. See /docs/idempotency.

string

Request Body

Section titled “Request Body ”
Media type application/json
Any of:
Text
object
messaging_product
required
string
Allowed values: whatsapp
recipient_type
string
Allowed values: individual
to
required
string
type
required
string
Allowed values: text
text
required
object
body
required
string
>= 1 characters <= 4096 characters
preview_url
boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Message accepted for delivery, or read receipt sent.

Media type application/json
object
data
required
object
id
required
string
object
required
string
Allowed values: message
to
string
type
string
status
required
string
Allowed values: queued pending sent delivered read failed
created_at
string format: date-time
conversation_id
string
message_id
string
error
object
code
required
string
message
required
string
provider_code
required
number | null
request_id
required
string
Example 
{
  "data": {
    "id": "msg_01HXYZABCDEFGHJKMNPQRSTVWX",
    "object": "message",
    "status": "queued"
  }
}

400

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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"
  }
}

502

Section titled “502 ”

Upstream WhatsApp 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"
  }
}

503

Section titled “503 ”

Service unavailable

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