ChatKomodo Docs Home Sign in

API reference · WhatsApp features

WhatsApp account

Send a presence update

POST/v1/sessions/{sessionId}/presence

Sets the presence of the account, or shows "typing" or "recording" in a chat.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • typestringrequired
    One of: available, unavailable, composing, recording, paused
  • jidstring
    Chat the update is for (typing and recording indicators)

Responses

  • 200Sent
    Response fields
    • okbooleanrequired
  • 400The body is not valid JSON
  • 401Missing or invalid credentials
  • 403The API key is restricted to other sessions
  • 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/presence" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "available",
  "jid": "[email protected]"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/presence', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "available",
    "jid": "[email protected]"
  }),
});
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/presence",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "type": "available",
        "jid": "[email protected]",
    },
    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/presence', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'type' => 'available',
        'jid' => '[email protected]',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true
}

Get WhatsApp privacy settings

GET/v1/sessions/{sessionId}/privacy

Fetches the privacy settings of the account from WhatsApp. The result is a map of setting name to value exactly as WhatsApp returns it. For data-subject export and erasure see the privacy tag.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Responses

  • 200Privacy settings
  • 401Missing or invalid credentials
  • 403The API key is restricted to other sessions
  • 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 "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);
import os
import requests

res = requests.get(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('GET', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{}

Set read receipts privacy

PUT/v1/sessions/{sessionId}/privacy/read-receipts

Turns read receipts on or off for the account.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • valuestringrequired
    all sends read receipts, none does not
    One of: all, none

Responses

  • 200Updated
    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 PUT "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/read-receipts" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "all"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/read-receipts', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "value": "all"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);
import os
import requests

res = requests.put(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/read-receipts",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "value": "all",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PUT', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/read-receipts', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'value' => 'all',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true
}

Set online visibility privacy

PUT/v1/sessions/{sessionId}/privacy/online

Controls who can see when the account is online.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • valuestringrequired
    all: everyone; match_last_seen: same audience as last seen
    One of: all, match_last_seen

Responses

  • 200Updated
    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 PUT "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/online" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "all"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/online', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "value": "all"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);
import os
import requests

res = requests.put(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/online",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "value": "all",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PUT', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/privacy/online', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'value' => 'all',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true
}

Set a profile picture

PUT/v1/sessions/{sessionId}/profile/picture

Downloads an image from a public URL (max 5 MB, 15-second limit, private addresses refused) and sets it as the picture of the account or of a group.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • jidstringrequired
    JID whose picture is set: the account itself or a group
  • image_urlstringrequired
    Public http(s) URL of the image

Responses

  • 200Updated
    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 PUT "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/picture" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jid": "[email protected]",
  "image_url": "https://example.com/file.jpg"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/picture', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "jid": "[email protected]",
    "image_url": "https://example.com/file.jpg"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);
import os
import requests

res = requests.put(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/picture",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "jid": "[email protected]",
        "image_url": "https://example.com/file.jpg",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PUT', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/picture', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'jid' => '[email protected]',
        'image_url' => 'https://example.com/file.jpg',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true
}

Set the About text

PUT/v1/sessions/{sessionId}/profile/status

Changes the About (status text) of the account.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • statusstringrequired
    New About text

Responses

  • 200Updated
    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 PUT "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/status" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "Open Mon–Sat 9:00–17:00"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/status', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "Open Mon–Sat 9:00–17:00"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);
import os
import requests

res = requests.put(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/status",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "status": "Open Mon–Sat 9:00–17:00",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PUT', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/profile/status', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'status' => 'Open Mon–Sat 9:00–17:00',
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true
}

Turn call auto-reject on or off

POST/v1/sessions/{sessionId}/calls/auto-reject

When on, incoming WhatsApp call offers on this session are rejected automatically. The setting is stored without contacting WhatsApp, so it also works while the session is offline; only the value true turns it on.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • enabledbooleanrequired

Responses

  • 200Saved
    Response fields
    • okbooleanrequired
    • auto_rejectbooleanrequired
      The submitted value
  • 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
Request
curl -X POST "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/calls/auto-reject" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/calls/auto-reject', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": true
  }),
});
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/calls/auto-reject",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "enabled": True,
    },
    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/calls/auto-reject', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'enabled' => true,
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "ok": true,
  "auto_reject": true
}