Status

Post WhatsApp Status updates (stories).

Post a Status update

POST/v1/sessions/{sessionId}/status

Posts a text or media Status update through the normal send pipeline (pacing and monthly quota apply). The response only confirms that the request was handed over, not the delivery result.

Path parameters

sessionIdstringrequired
Session (device) id

Request body

typestring
Message type, default text (image, video, … for media)
bodystring
Text of a text Status
media_r2_keystring
Media key from /v1/media/upload-url
captionstring
jid_listarray of string
JIDs the Status is delivered to

Responses

200Handed over
Response fields
- message_idstringrequired
- okbooleanrequired
401Missing or invalid credentials
403The API key is restricted to other sessions, or the operation is not available to CS-agent logins
404Unknown session, or a session of another tenant
409The session is not connected

Request

curl -X POST "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "text",
  "body": "New menu this week 🍜"
}'

const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "text",
    "body": "New menu this week 🍜"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.post(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "type": "text",
        "body": "New menu this week 🍜",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('POST', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'type' => 'text',
        'body' => 'New menu this week 🍜',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "message_id": "01JA5V6Q8M2H7G4K9P3T0R1S2X",
  "ok": true
}

Post a text Status

POST/v1/sessions/{sessionId}/status/text

Posts a text Status straight through the WhatsApp connection (not queued, not logged in the message history).

Path parameters

sessionIdstringrequired
Session (device) id

Request body

textstringrequired
Status text
background_colorstring
Background colour, passed unchanged to the WhatsApp library

Responses

200Posted
Response fields
- okbooleanrequired
400The body is not valid JSON
401Missing or invalid credentials
403The API key is restricted to other sessions, or the operation is not available to CS-agent logins
404Unknown session, or a session of another tenant
409The session is not connected
500WhatsApp operation failed: WhatsApp or the library rejected the call. The gateway does not validate this body, so missing or malformed fields end up here too

Request

curl -X POST "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/text" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "New menu this week 🍜",
  "background_color": "#0a7350"
}'

const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/text', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "New menu this week 🍜",
    "background_color": "#0a7350"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.post(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/text",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "text": "New menu this week 🍜",
        "background_color": "#0a7350",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('POST', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/text', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'text' => 'New menu this week 🍜',
        'background_color' => '#0a7350',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "ok": true
}

Post an image Status

POST/v1/sessions/{sessionId}/status/image

Downloads an image from a public URL (max 5 MB, 15-second limit, private addresses refused) and posts it as a Status straight through the WhatsApp connection (not queued, not logged in the message history).

Path parameters

sessionIdstringrequired
Session (device) id

Request body

image_urlstringrequired
Public http(s) URL of the image
captionstring

Responses

200Posted
Response fields
- okbooleanrequired
400The body is not valid JSON, or image_url is missing, is not an http(s) URL, answers with an HTTP error, is larger than 5 MB, or points at a private/local address (error starts with image_url)
401Missing or invalid credentials
403The API key is restricted to other sessions, or the operation is not available to CS-agent logins
404Unknown session, or a session of another tenant
409The session is not connected
500WhatsApp operation failed

Request

curl -X POST "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/image" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://example.com/new-menu.jpg",
  "caption": "New menu this week 🍜"
}'

const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/image', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "image_url": "https://example.com/new-menu.jpg",
    "caption": "New menu this week 🍜"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.post(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/image",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "image_url": "https://example.com/new-menu.jpg",
        "caption": "New menu this week 🍜",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('POST', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/status/image', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'image_url' => 'https://example.com/new-menu.jpg',
        'caption' => 'New menu this week 🍜',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "ok": true
}