API Reference

Request Body

{
  "type": "text",
  "receiver": "string (required) - Phone number with country code (e.g., 628123456789)",
  "message": "string (required) - Message content",
  "reply_to": "string (optional) - message_id of an earlier message to quote",
  "typing": "boolean (optional, default false) - WhatsApp (QR) only. true shows \"typing...\" before sending, so the reply takes up to 3 seconds longer"
}

Example Request

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "text",
  "receiver": "628123456789",
  "message": "Hello! This is a test message."
}

Success Response (200 OK)

{
  "message": "Message sent.",
  "data": { "message_id": "3EB0C767D0B1A2F4E5A9B3" }
}

Error Response

{
  "code": "invalid_receiver",
  "message": "Invalid WhatsApp number."
}

Request Body

{
  "type": "media",
  "receiver": "string (required) - Phone number with country code (e.g., 628123456789)",
  "url": "string (required) - Media URL",
  "caption": "string (optional)",
  "media_type": "string (required) - image|video|audio|file",
  "voice": "boolean (optional) - Send audio as a voice note",
  "reply_to": "string (optional) - message_id of an earlier message to quote",
  "typing": "boolean (optional, default false) - WhatsApp (QR) only. true shows \"typing...\" before sending, so the reply takes up to 3 seconds longer"
}

Example Request

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "media",
  "receiver": "628123456789",
  "url": "https://example.com/image.jpg",
  "caption": "Check out this image!",
  "media_type": "image"
}

Media Types

• image: JPG, PNG images
• video: MP4, 3GP videos
• audio: MP3, OGG, AAC audio files
• file: PDF, DOC, XLS, and other documents

Success Response (200 OK)

{
  "message": "Media sent.",
  "data": { "message_id": "3EB0C767D0B1A2F4E5A9B3" }
}

Request Body

{
  "type": "buttons",
  "receiver": "string (required) - Phone number with country code (e.g., 628123456789)",
  "message": "string (required) - Message content",
  "footer": "string (optional) - Small text shown below the message",
  "typing": "boolean (optional, default false) - WhatsApp (QR) only. true shows \"typing...\" before sending, so the reply takes up to 3 seconds longer",
  "buttons": [
    {
      "type": "string (required) - quick_reply|url|call|copy",
      "text": "string (required) - Button label, max 25 characters (20 on Official channels)",
      "value": "string - Required for url, call and copy. Optional for quick_reply"
    }
  ]
}

Button Types

• quick_reply: Sends the button back to you as an incoming message. value is an optional reply ID, if empty, the label is used as the ID.
• url: Opens a link. value must start with http:// or https://.
• call: Dials a number. value is the phone number with country code (e.g., +628123456789).
• copy: Copies text to the clipboard. value is the text to copy (e.g., a promo or OTP code).

You can send 1 to 3 buttons per message.

Example Request

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "buttons",
  "receiver": "628123456789",
  "message": "Your order #1024 has shipped. What would you like to do?",
  "footer": "KonekSip Store",
  "buttons": [
    { "type": "quick_reply", "text": "Contact support" },
    { "type": "url", "text": "Track order", "value": "https://example.com/track/1024" },
    { "type": "call", "text": "Call us", "value": "+628123456789" }
  ]
}

Success Response (200 OK)

{
  "message": "Buttons sent.",
  "data": { "message_id": "3EB0C767D0B1A2F4E5A9B3" }
}

Error Response

{
  "code": "unsupported_channel",
  "message": "This channel does not support this action."
}

When a customer taps a quick_reply button, it arrives on your webhook as a message.received event. The button label is in message and the reply ID is in button_reply.id.

Request Body

{
  "type": "list",
  "receiver": "string (required) - Phone number with country code (e.g., 628123456789)",
  "message": "string (required) - Message content, max 1024 characters",
  "footer": "string (optional) - Small text below the message, max 60 characters",
  "button_text": "string (required) - Label of the button that opens the list, max 20 characters",
  "sections": [
    {
      "title": "string - Section heading, max 24 characters. Required when there is more than one section",
      "rows": [
        {
          "id": "string (required) - Value returned to your webhook, max 200 characters",
          "title": "string (required) - Row title, max 24 characters",
          "description": "string (optional) - Row description, max 72 characters"
        }
      ]
    }
  ]
}

Limits

• A list has 1 to 10 sections and at most 10 rows in total.
• Every section needs a title when there is more than one section.
• The limits on titles and descriptions are WhatsApp's own, a request over a limit is rejected with validation_failed before anything is sent.

Example Request

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "list",
  "receiver": "628123456789",
  "message": "Which topic do you need help with?",
  "footer": "KonekSip Support",
  "button_text": "Choose a topic",
  "sections": [
    {
      "title": "Orders",
      "rows": [
        { "id": "order_status", "title": "Order status", "description": "Where is my package?" },
        { "id": "order_cancel", "title": "Cancel an order" }
      ]
    },
    {
      "title": "Account",
      "rows": [{ "id": "account_login", "title": "Login problem" }]
    }
  ]
}

Success Response (200 OK)

{
  "message": "List sent.",
  "data": { "message_id": "wamid.HBgM..." }
}

When the customer picks a row it arrives on your webhook as a message.received event. The row title is in message and the row id is in button_reply.id.

Request Body

{
  "type": "template",
  "receiver": "string (required) - Phone number with country code (e.g., 628123456789)",
  "template_name": "string (required) - Name of the approved template",
  "language_code": "string (required) - e.g., en_US, id",
  "components": "array (optional) - Template parameters in Meta's components format",
  "otp_code": "string (optional) - One-time code for an authentication template, up to 15 characters. Replaces components.",
  "header_format": "string (optional) - IMAGE|VIDEO|DOCUMENT, use together with media",
  "media": "string (optional) - Public URL of the header media"
}

Example Request

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "template",
  "receiver": "628123456789",
  "template_name": "order_shipped",
  "language_code": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "#1024" }
      ]
    }
  ]
}

Example Request: one-time code

POST /api/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "template",
  "receiver": "628123456789",
  "template_name": "login_code",
  "language_code": "id",
  "otp_code": "482913"
}

For an authentication template, send only otp_code: KonekSip puts the code in the message body and in the Copy code button, so components is not needed. The code can have up to 15 characters. It is kept masked as ****** in the message history and the inbox.

Success Response (200 OK)

{
  "message": "Template sent.",
  "data": { "message_id": "wamid.HBgM..." }
}

Example Request

POST /api/chats/628123456789/read-receipts
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "Chat marked as read."
}

Request Body

{
  "emoji": "string (required) - One emoji, or an empty string to remove your reaction"
}

Example Request

PUT /api/messages/3EB0C767D0B1A2F4E5/reaction
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "emoji": "👍"
}

Success Response (200 OK)

{
  "message": "Reaction added."
}

Request Body

{
  "message": "string (required) - The new text"
}

Example Request

PATCH /api/messages/3EB0C767D0B1A2F4E5
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "message": "Hello! This is the corrected text."
}

Success Response (200 OK)

{
  "message": "Message edited."
}

Query Parameters

• scope - everyone (default) or me (remove it from this channel only)
• delete_media - true to also delete the stored media file, only with scope=me

Example Request

DELETE /api/messages/3EB0C767D0B1A2F4E5?scope=everyone
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "Message deleted for everyone."
}

Query Parameters

• status - optional, open, pending or resolved.
• limit - optional, 1 to 100, default 20.
• cursor - optional, the next_cursor of the previous page.

Example Request

GET /api/conversations?status=open&limit=20
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "OK",
  "data": [
    {
      "receiver": "628123456789",
      "name": "Dewi Lestari",
      "status": "open",
      "priority": "high",
      "assigned_to": { "id": 3, "name": "Sari Agent" },
      "last_message": {
        "id": "3EB0C767D0B1A2F4E5A9B3",
        "conversation": "628123456789",
        "from_me": false,
        "type": "text",
        "text": "Hello, is the order shipped?",
        "status": "read",
        "timestamp": 1735689600
      }
    }
  ],
  "next_cursor": "1735689600_4821"
}

receiver is the phone number or the group ID . Use it in the next endpoint. last_message has the same shape as a message.

Query Parameters

• limit - optional, 1 to 100, default 50.
• before - optional, the next_cursor of the previous page, for older messages.

Example Request

GET /api/conversations/628123456789/messages?limit=50
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "OK",
  "data": [
    {
      "id": "3EB0C767D0B1A2F4E5A9B3",
      "conversation": "628123456789",
      "from_me": false,
      "type": "text",
      "text": "Hello, is the order shipped?",
      "status": "read",
      "timestamp": 1735689600
    }],
  "next_cursor": "4790"
}

A conversation that does not exist returns an empty data list.

Example Request

GET /api/messages/3EB0C767D0B1A2F4E5
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "OK",
  "data": {
    "id": "3EB0C767D0B1A2F4E5A9B3",
    "conversation": "628123456789",
    "from_me": false,
    "type": "image",
    "text": "My receipt",
    "media": { "url": "https://cdn.example.com/receipt.jpg", "mimetype": "image/jpeg" },
    "status": "read",
    "timestamp": 1735689600
  }
}

Message Fields

• type - text, image, video, audio, sticker, file, interactive (buttons and lists), template, email or other.
• text - the text, the caption of a media message, the template name or the email body.
• media - only on media messages: url and mimetype.
• email - only on emails: subject.
• status - unread, read, sent, delivered or failed, with error_reason when it failed.
• timestamp - Unix epoch seconds.

An unknown ID returns not_found (404).

Query Parameters

• number - optional, exact phone number, digits only.
• search - optional, matches name, number, email and company.
• limit - optional, 1 to 100, default 50.
• cursor - optional, the next_cursor of the previous page.

Example Request

GET /api/contacts?number=628123456789
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "OK",
  "data": [
    {
      "id": 12,
      "number": "628123456789",
      "name": "Dewi Lestari",
      "email": "[email protected]",
      "company": "PT Maju",
      "status": "customer",
      "tags": ["vip"],
      "custom_fields": { "order_id": "A-77" },
      "opted_out": false,
      "created_at": 1735600000
    }
  ],
  "next_cursor": null
}

custom_fields are the extra fields of the customer.

Example Request

GET /api/templates
Authorization: Bearer YOUR_API_KEY

Success Response (200 OK)

{
  "message": "OK",
  "data": [
    { "id": "1234567890", "name": "order_update", "language": "en", "status": "APPROVED", "category": "UTILITY" }
  ]
}

The exact fields of each template are the ones Meta returns for it.

Success Response

{
  "message": "OK",
  "data": {
    "id": "uuid-of-the-channel",
    "name": "My Channel",
    "address": "628123456789",
    "type": "whatsapp_qr",
    "status": "connected",
    "verified": false,
    "verified_name": null
  }
}

status is connected or disconnected. type is whatsapp_qr (Unofficial, QR code), whatsapp_cloud (Official, Cloud API) , and address is the WhatsApp number . verified and verified_name show whether the connected number has registered a WhatsApp Business display name, this is not Meta's official verified ("Green Tick") badge. Both are null while the channel is disconnected.

Example: Text Message

{
  "id": "evt_5b9f6a0e-3c1d-4c0e-9a77-1f2a8d4e6b10",
  "type": "message.received",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "message_id": "3EB0...",
    "timestamp": 1735689600,
    "from": "628123456789",
    "participant": null,
    "is_group": false,
    "is_me": false,
    "message": "Hello! I need information about your products.",
    "media": null,
    "button_reply": null
  }
}

Example: Media Message

{
  "id": "evt_8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "type": "message.received",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "message_id": "3EB0...",
    "timestamp": 1735689600,
    "from": "628123456789",
    "participant": null,
    "is_group": false,
    "is_me": false,
    "message": "caption text, if any",
    "media": {
      "url": "https://.../inbound/.../file.jpg",
      "mimetype": "image/jpeg",
      "type": "image"
    },
    "button_reply": null
  }
}

Example: WhatsApp username (BSUID)

{
  "id": "evt_8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
  "type": "message.received",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "message_id": "wamid.HBgM...",
    "timestamp": 1735689600,
    "from": "ID.13491208655302741918",
    "participant": null,
    "is_group": false,
    "is_me": false,
    "message": "Hello, I use a username",
    "media": null,
    "button_reply": null,
    "user_id": "ID.13491208655302741918",
    "username": "raka.id"
  }
}

user_id is the customer's BSUID and username the WhatsApp username when there is one, both are null on other channels. from is the phone number while Meta shares it, and the BSUID otherwise. The to of a message.status event follows the same rule.

Example: Button Reply

{
  "id": "evt_a1b2c3d4-e5f6-4789-8abc-def012345678",
  "type": "message.received",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "message_id": "3EB0...",
    "timestamp": 1735689600,
    "from": "628123456789",
    "participant": null,
    "is_group": false,
    "is_me": false,
    "message": "Contact support",
    "media": null,
    "button_reply": {
      "id": "support",
      "text": "Contact support"
    }
  }
}

button_reply is null unless the customer tapped a quick reply button or picked a list row. id is the value you set on the button (or the button label if you left it empty) or the row id, and text is the label or the row title. message also carries it.

Inside data, message_id identifies the message and timestamp (Unix epoch seconds) is when it was sent or received. from/to are plain WhatsApp IDs (no @s.whatsapp.net suffix ) , for group chats (is_group: true) from is the group's ID rather than a phone number, and participant is the member who wrote the message. participant is null outside groups. media.type is image, video, audio, sticker or file.

Sent whenever a message you sent changes delivery state (sent, delivered, read, or failed for Cloud API).

{
  "id": "evt_3d2c1b0a-9f8e-4d7c-b6a5-4f3e2d1c0b9a",
  "type": "message.status",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "message_id": "3EB0...",
    "timestamp": 1735689650,
    "to": "628123456789",
    "status": "delivered"
  }
}

Sent when a conversation is assigned, claimed or released, by a team member or automatically. assigned_to is null when nobody has it now.

{
  "id": "evt_6c5b4a39-2817-4f6e-9d0c-1b2a3f4e5d6c",
  "type": "conversation.assigned",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "receiver": "628123456789",
    "status": "open",
    "assigned_to": { "id": 3, "name": "Sari Agent" },
    "assigned_by": { "id": 1, "name": "Hel Owner" },
    "department": { "id": 1, "name": "Customer Service" }
  }
}

Sent when a team member marks a conversation as resolved.

{
  "id": "evt_6c5b4a39-2817-4f6e-9d0c-1b2a3f4e5d6c",
  "type": "conversation.closed",
  "created_at": 1735689601,
  "channel_id": "uuid-of-the-channel",
  "data": {
    "receiver": "628123456789",
    "status": "resolved",
    "closed_by": { "id": 3, "name": "Sari Agent" },
    "assigned_to": { "id": 3, "name": "Sari Agent" }
  }
}