ChatKomodo Docs Home Sign in

API reference · WhatsApp features

Blocklist

List blocked recipients

GET/v1/sessions/{sessionId}/blocklist

Recipients this session must not send to, newest first (max 10 000). This is the gateway's own list; the list kept by WhatsApp is at GET …/wa-blocklist.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Responses

  • 200Blocked recipients
    Response fields
    • blocklistarray of objectrequired
    • blocklist[].chat_idstringrequired
      JID
    • blocklist[].reasonstring | nullrequired
    • blocklist[].added_atintegerrequired
      Time added (Unix epoch, milliseconds)
  • 401Missing or invalid credentials
  • 403The API key is restricted to other sessions
  • 404Unknown session, or a session of another tenant
Request
curl "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist', {
  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/blocklist",
    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/blocklist', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "blocklist": [
    {
      "chat_id": "+447700900123",
      "reason": "string",
      "added_at": 1767225600000
    }
  ]
}

Block a recipient

POST/v1/sessions/{sessionId}/blocklist

Adds a chat to the session blocklist (an existing entry is replaced). Sends from this session to a blocked chat are not delivered and come back with status blocked. This does not block the contact on WhatsApp; see POST …/block for that.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • chat_idstringrequired
    Phone number or JID; local-format numbers are resolved against the business country
    1–64 characters
  • reasonstring | null
    Free-text note
    Up to 200 characters

Responses

  • 200Blocked
    Response fields
    • okbooleanrequired
    • chat_idstringrequired
      The normalised JID that was stored
  • 400Invalid body (VALIDATION_FAILED, INVALID_JSON) or chat_id is neither a phone number nor a JID (INVALID_JID)
  • 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/blocklist" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "+447700900123",
  "reason": "opt-out"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "chat_id": "+447700900123",
    "reason": "opt-out"
  }),
});
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/blocklist",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "chat_id": "+447700900123",
        "reason": "opt-out",
    },
    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/blocklist', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'chat_id' => '+447700900123',
        'reason' => 'opt-out',
    ],
]);

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

Unblock a recipient

DEL/v1/sessions/{sessionId}/blocklist/{chatId}

Removes a chat from the session blocklist. Answers 200 with deleted: 0 when it was not listed.

Path parameters

  • sessionIdstringrequired
    Session (device) id
  • chatIdstringrequired
    Phone number or JID, URL-encoded; local-format numbers are resolved against the business country

Responses

  • 200Result
    Response fields
    • okbooleanrequired
    • deletedintegerrequired
      Blocklist entries removed
  • 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 DELETE "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist/447700900123%40s.whatsapp.net" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist/447700900123%40s.whatsapp.net', {
  method: 'DELETE',
  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.delete(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist/447700900123%40s.whatsapp.net",
    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('DELETE', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/blocklist/447700900123%40s.whatsapp.net', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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

Block a contact on WhatsApp

POST/v1/sessions/{sessionId}/block

Blocks a contact in the WhatsApp account itself. This is separate from the gateway recipient blocklist.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

Responses

  • 200Blocked
    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/block" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jid": "[email protected]"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/block', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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/block",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "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/block', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'jid' => '[email protected]',
    ],
]);

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

Unblock a contact on WhatsApp

POST/v1/sessions/{sessionId}/unblock

Removes a contact from the block list of the WhatsApp account itself.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • jidstringrequired
    JID of the contact

Responses

  • 200Unblocked
    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/unblock" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jid": "[email protected]"
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/unblock', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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/unblock",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "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/unblock', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'jid' => '[email protected]',
    ],
]);

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

List contacts blocked on WhatsApp

GET/v1/sessions/{sessionId}/wa-blocklist

Fetches the block list of the WhatsApp account from WhatsApp. The gateway recipient blocklist is at GET …/blocklist.

Path parameters

  • sessionIdstringrequired
    Session (device) id

Responses

  • 200Blocked JIDs
    Response fields
    • blocklistarray of stringrequired
      JIDs
  • 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/wa-blocklist" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/wa-blocklist', {
  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/wa-blocklist",
    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/wa-blocklist', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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