Get WhatsApp Messages

curl --request GET \
  --url https://api.callkaro.ai/whatsapp/messages \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.callkaro.ai/whatsapp/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/whatsapp/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.callkaro.ai/whatsapp/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/whatsapp/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Messages fetched",
  "data": {
    "user_phone_number": "919876543210",
    "agent_phone_number": "919000000000",
    "limit": 50,
    "count": 3,
    "messages": [
      {
        "name": "inbound",
        "time": "2026-03-01 10:01:00",
        "status": "read",
        "type": "text",
        "body": "Where is my order?",
        "msg_id": "wamid.AAA"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:02:00",
        "status": "delivered",
        "type": "template",
        "body": "[Template] Hi Rahul, your order #1234 has shipped. - Buttons: Track | Support",
        "msg_id": "wamid.BBB"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:03:00",
        "status": "sent",
        "type": "text",
        "body": "It should arrive tomorrow. [Tool calls: get_order_status({\"id\":\"1234\"})->shipped]",
        "msg_id": "wamid.CCC",
        "tool_calls": [
          {
            "name": "get_order_status",
            "arguments": "{\"id\":\"1234\"}",
            "content": "shipped"
          }
        ]
      }
    ]
  }
}

{
  "status": "error",
  "message": "user_phone_number is required"
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

GET

messages

Get WhatsApp Messages

curl --request GET \
  --url https://api.callkaro.ai/whatsapp/messages \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.callkaro.ai/whatsapp/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/whatsapp/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.callkaro.ai/whatsapp/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/whatsapp/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Messages fetched",
  "data": {
    "user_phone_number": "919876543210",
    "agent_phone_number": "919000000000",
    "limit": 50,
    "count": 3,
    "messages": [
      {
        "name": "inbound",
        "time": "2026-03-01 10:01:00",
        "status": "read",
        "type": "text",
        "body": "Where is my order?",
        "msg_id": "wamid.AAA"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:02:00",
        "status": "delivered",
        "type": "template",
        "body": "[Template] Hi Rahul, your order #1234 has shipped. - Buttons: Track | Support",
        "msg_id": "wamid.BBB"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:03:00",
        "status": "sent",
        "type": "text",
        "body": "It should arrive tomorrow. [Tool calls: get_order_status({\"id\":\"1234\"})->shipped]",
        "msg_id": "wamid.CCC",
        "tool_calls": [
          {
            "name": "get_order_status",
            "arguments": "{\"id\":\"1234\"}",
            "content": "shipped"
          }
        ]
      }
    ]
  }
}

{
  "status": "error",
  "message": "user_phone_number is required"
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

Returns the conversation history for one contact, in the exact form your AI agent is shown it. Only user_phone_number is required.

Quick Example

curl -X GET "https://api.callkaro.ai/whatsapp/messages?user_phone_number=919876543210&limit=50" \
  -H "X-API-KEY: YOUR_API_KEY"

Restrict it to one of your numbers:

curl -X GET "https://api.callkaro.ai/whatsapp/messages?user_phone_number=919876543210&agent_phone_number=919000000000" \
  -H "X-API-KEY: YOUR_API_KEY"

Response

Messages come back oldest first, the same order the conversation is fed to the model.

{
  "status": "success",
  "message": "Messages fetched",
  "data": {
    "user_phone_number": "919876543210",
    "agent_phone_number": "919000000000",
    "limit": 50,
    "count": 3,
    "messages": [
      {
        "name": "inbound",
        "time": "2026-03-01 10:01:00",
        "status": "read",
        "type": "text",
        "body": "Where is my order?",
        "msg_id": "wamid.AAA"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:02:00",
        "status": "delivered",
        "type": "template",
        "body": "[Template] Hi Rahul, your order #1234 has shipped. — Buttons: Track | Support",
        "msg_id": "wamid.BBB"
      },
      {
        "name": "outbound",
        "time": "2026-03-01 10:03:00",
        "status": "sent",
        "type": "text",
        "body": "It should arrive tomorrow. [Tool calls: get_order_status({\"id\":\"1234\"})->shipped]",
        "msg_id": "wamid.CCC",
        "tool_calls": [
          { "name": "get_order_status", "arguments": "{\"id\":\"1234\"}", "content": "shipped" }
        ]
      }
    ]
  }
}

Fields

string

inbound (from the contact) or outbound (from your agent).

string

YYYY-MM-DD HH:MM:SS, IST.

string

Whether the message reached the user. See the table below — sent does not mean it arrived.

string

text, template, interactive, image, video, audio, document, contact, and so on.

string

The message rendered the way the agent sees it. A template arrives as readable text rather than a raw components blob, so you do not have to reassemble it — see below.

string

WhatsApp’s wamid. Empty for messages WhatsApp never accepted.

string

Present only on media messages: the stored file URL.

array

Present only on outbound messages where the agent called functions. Also summarised inside body, because that is how the model sees it — this field is the structured version so you do not have to parse it back out.

What `status` means

Only the first three appear in this response.

Status	Reached the user?	Meaning
`read`	Yes	Delivered and opened by the user
`delivered`	Yes	On the user’s device, not yet opened
`sent`	Not yet	Accepted by WhatsApp but not on the user’s device — phone off, no network, or still in flight
`failed` / `not sent`	No	WhatsApp rejected it or could not deliver. Excluded from this response

sent is the one to watch: it is returned, but it means the message has not reached the user. Treat only delivered and read as arrived.

How `body` is built

Non-text messages are flattened into one readable string, using the same renderer that builds the model’s context. That is deliberate: what this endpoint returns and what the agent was given cannot drift apart.

Stored type	`body` you receive
`text`	the text itself
`template`	`[Template] <body text> — Buttons: A \| B — <footer>`
`interactive`	`[Interactive] <body text> — Buttons: A \| B`
`image` / `video` / `audio` / `document`	`[Image]` and the caption, with the URL in `content_link`
`location`	`[Location shared] …` plus a Google Maps link
any outbound with functions	the reply text, then `[Tool calls: name(args)->result]`

What is excluded

To match the agent’s view exactly, the following never appear:

Internal records — developer rows (system notes, scheduling markers) are not messages anyone sent
Messages that never reached the user — failed and not sent are excluded. sent is returned, but see the status table above: it means WhatsApp accepted the message, not that it arrived
Anything before a chat reset — if the conversation was cleared, messages from before that point are excluded, exactly as they are for the agent

limit defaults to 50 and is capped at 200. Values above the cap are silently reduced rather than rejected.

Use Cases

Show history in your own UI without building a renderer for every WhatsApp message type
Hand context to another system — a CRM note, a support ticket, a human handover
Debug an agent reply by reading the exact context it was given, including the tool calls it made

Scoped to the account behind the API key — it can only ever read your own conversations. Passing another account’s number returns an empty list, not an error.

Authorizations

X-API-KEY

string

header

required

API key from https://callkaro.ai/dashboard/api-key

Query Parameters

user_phone_number

string

required

The contact's number, digits only including country code.

agent_phone_number

string

Restrict to one of your WhatsApp numbers. Omit to return this contact's conversation across every number of yours.

limit

integer

default:50

How many messages to return, newest kept. Values above 200 are capped at 200.

Required range: 1 <= x <= 200

Response

Messages, oldest first

status

string

Example:

"success"

message

string

Example:

"Messages fetched"

data

object

Show child attributes

​Quick Example

​Response

​Fields

​What status means

​How body is built

​What is excluded

​Use Cases

Authorizations

Query Parameters

Response

Quick Example

Response

Fields

What `status` means

How `body` is built

What is excluded

Use Cases