Send a WhatsApp message

POST

/messages

curl --request POST \
  --url https://api-kckit.kirim.chat/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "from": "example", "to": "example", "type": "text", "text": { "body": "example" } }'

• Production
• Local development

Send a message of any supported type (text, template, image, document, video, audio, interactive). Pass Idempotency-Key to safely retry on network failure.

Authorizations

• bearerAuth

Parameters

Header Parameters

idempotency-key

Optional idempotency token. See /docs/idempotency.

string

Request Body

Media type application/json

One of:

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: text

text

required

object

body

required

string

>= 1 characters <= 4096 characters

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: image

image

required

object

url

required

string format: uri

caption

string

<= 1024 characters

filename

string

<= 255 characters

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: document

document

required

object

url

required

string format: uri

caption

string

<= 1024 characters

filename

string

<= 255 characters

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: video

video

required

object

url

required

string format: uri

caption

string

<= 1024 characters

filename

string

<= 255 characters

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: audio

audio

required

object

url

required

string format: uri

caption

string

<= 1024 characters

filename

string

<= 255 characters

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: template

template

required

object

name

required

string

>= 1 characters

language

required

string

>= 2 characters

components

Array<object>

object

type

required

string

Allowed values: header body button

sub_type

string

Allowed values: url quick_reply copy_code flow

index

integer

parameters

Array<object>

object

key

additional properties

object

object

from

string

/^\+[1-9]\d{6,14}$/

to

required

string

/^\+[1-9]\d{6,14}$/

type

required

string

Allowed values: interactive

interactive

required

One of:

object

object

type

required

string

Allowed values: cta_url

body

required

object

text

required

string

>= 1 characters <= 1024 characters

action

required

object

name

required

string

Allowed values: cta_url

parameters

required

object

display_text

required

string

>= 1 characters <= 20 characters

url

required

string format: uri

object

object

type

required

string

Allowed values: list

header

object

type

required

string

Allowed values: text

text

required

string

>= 1 characters <= 60 characters

body

required

object

text

required

string

>= 1 characters <= 1024 characters

footer

object

text

required

string

>= 1 characters <= 60 characters

action

required

object

button

required

string

>= 1 characters <= 20 characters

sections

required

Array<object>

>= 1 items

object

title

string

<= 24 characters

rows

required

Array<object>

>= 1 items

object

id

required

string

>= 1 characters <= 200 characters

title

required

string

>= 1 characters <= 24 characters

description

string

<= 72 characters

Responses

200

Message accepted for delivery

Media type application/json

object

data

required

object

id

required

string

object

required

string

Allowed values: message

to

required

string

type

required

string

status

required

string

Allowed values: queued pending sent delivered read failed

created_at

required

string format: date-time

conversation_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

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

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

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

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