Code samples use your device . Create an API key under API keys.

API reference · Customers

Consent

Who agreed to be messaged and who asked to stop. Replies such as STOP opt people out automatically; broadcasts skip them.

GET/v1/consent

Who agreed to be messaged and who asked to stop, newest change first, with totals.

Query parameters

statusstring
One of: opted_in, opted_out
qstring
Phone search
limitinteger
From 1 to 500
beforeinteger | null
Cursor: the next_before of the previous page
before_idstring
Cursor tie-breaker: the next_before_id of the previous page (send it together with before, otherwise records sharing one timestamp can be skipped)

Responses

200Consent records
Response fields
- summaryobjectrequired
- summary.opted_inintegerrequired
- summary.opted_outintegerrequired
- consentarray of objectrequired
- consent[].chat_idstringrequired
- consent[].phonestringrequired
  Digits with country code (no +)
- consent[].statusstringrequired
  One of: opted_in, opted_out
- consent[].sourcestringrequired
  How the status was set: the customer replied with a keyword, a person in the dashboard, a contacts import with opt_in, an API key, or a privacy erasure
  One of: keyword, manual, import, api, erasure
- consent[].notestring | nullrequired
- consent[].created_atintegerrequired
- consent[].updated_atintegerrequired
- next_beforeinteger | nullrequired
- next_before_idstring | nullrequired

Request

curl "https://api.chatkomodo.com/v1/consent" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/consent', {
  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/consent",
    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/consent', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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

Response 200

{
  "summary": {
    "opted_in": 1,
    "opted_out": 1
  },
  "consent": [
    {
      "chat_id": "+447700900123",
      "phone": "+447700900123",
      "status": "opted_in",
      "source": "keyword",
      "note": "Prefers delivery after 5 pm",
      "created_at": 1767225600000,
      "updated_at": 1767225600000
    }
  ],
  "next_before": 1767225600000,
  "next_before_id": "01JA5V6Q8M2H7G4K9P3T0R1S2X"
}

GET/v1/consent/config

Opt-out keywords, confirmation replies and enforcement settings.

Responses

200Config
Response fields
- enabledbooleanrequired
  Listen for opt-out / opt-in keywords in inbound messages (STOP, UNSUBSCRIBE, START, … in several languages)
- optout_keywordsarray of stringrequired
- optin_keywordsarray of stringrequired
- optout_replystring | nullrequired
  null = default confirmation in the tenant language, empty string = send no confirmation
- optin_replystring | nullrequired
- enforce_apibooleanrequired
  Refuse 1:1 sends to opted-out recipients with 409 RECIPIENT_OPTED_OUT (default: send and return a warning)
- require_attestationbooleanrequired
  Require consent_attested: true before a blast starts

Request

curl "https://api.chatkomodo.com/v1/consent/config" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/consent/config', {
  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/consent/config",
    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/consent/config', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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

Response 200

{
  "enabled": true,
  "optout_keywords": [
    "string"
  ],
  "optin_keywords": [
    "string"
  ],
  "optout_reply": "Hi Sam, your order has shipped.",
  "optin_reply": "Hi Sam, your order has shipped.",
  "enforce_api": true,
  "require_attestation": true
}

PUT/v1/consent/config

Update the consent configuration (partial update). Account owner only.

Request body

enabledboolean
Listen for opt-out / opt-in keywords in inbound messages (STOP, UNSUBSCRIBE, START, … in several languages)
optout_keywordsarray of string
optin_keywordsarray of string
optout_replystring | null
null = default confirmation in the tenant language, empty string = send no confirmation
optin_replystring | null
enforce_apiboolean
Refuse 1:1 sends to opted-out recipients with 409 RECIPIENT_OPTED_OUT (default: send and return a warning)
require_attestationboolean
Require consent_attested: true before a blast starts

Responses

200Saved config
Response fields
- enabledbooleanrequired
  Listen for opt-out / opt-in keywords in inbound messages (STOP, UNSUBSCRIBE, START, … in several languages)
- optout_keywordsarray of stringrequired
- optin_keywordsarray of stringrequired
- optout_replystring | nullrequired
  null = default confirmation in the tenant language, empty string = send no confirmation
- optin_replystring | nullrequired
- enforce_apibooleanrequired
  Refuse 1:1 sends to opted-out recipients with 409 RECIPIENT_OPTED_OUT (default: send and return a warning)
- require_attestationbooleanrequired
  Require consent_attested: true before a blast starts
403Not the account owner

Request

curl -X PUT "https://api.chatkomodo.com/v1/consent/config" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "optout_keywords": [
    "stop",
    "unsubscribe"
  ],
  "enforce_api": true,
  "require_attestation": true
}'

const res = await fetch('https://api.chatkomodo.com/v1/consent/config', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": true,
    "optout_keywords": [
      "stop",
      "unsubscribe"
    ],
    "enforce_api": true,
    "require_attestation": 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.put(
    "https://api.chatkomodo.com/v1/consent/config",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "enabled": True,
        "optout_keywords": [
            "stop",
            "unsubscribe",
        ],
        "enforce_api": True,
        "require_attestation": True,
    },
    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/consent/config', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'enabled' => true,
        'optout_keywords' => [
            'stop',
            'unsubscribe',
        ],
        'enforce_api' => true,
        'require_attestation' => true,
    ],
]);

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

Response 200

{
  "enabled": true,
  "optout_keywords": [
    "string"
  ],
  "optin_keywords": [
    "string"
  ],
  "optout_reply": "Hi Sam, your order has shipped.",
  "optin_reply": "Hi Sam, your order has shipped.",
  "enforce_api": true,
  "require_attestation": true
}

GET/v1/consent/export

Download all consent records as CSV (phone,status,source,note,updated_at).

Responses

200CSV file

Request

curl "https://api.chatkomodo.com/v1/consent/export" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/consent/export', {
  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/consent/export",
    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/consent/export', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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

Response 200

text/csv — the file itself.

POST/v1/consent/bulk

Set the consent status of up to 10 000 numbers at once (e.g. importing a suppression list).

Request body

phonesarray of stringrequired
1–10 000 items
statusstringrequired
One of: opted_in, opted_out
notestring | null
Up to 200 characters

Responses

200Result
Response fields
- changedintegerrequired
- unchangedintegerrequired
- invalidintegerrequired

Request

curl -X POST "https://api.chatkomodo.com/v1/consent/bulk" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "+447700900123",
    "+12025550123"
  ],
  "status": "opted_out"
}'

const res = await fetch('https://api.chatkomodo.com/v1/consent/bulk', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phones": [
      "+447700900123",
      "+12025550123"
    ],
    "status": "opted_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/consent/bulk",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "phones": [
            "+447700900123",
            "+12025550123",
        ],
        "status": "opted_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/consent/bulk', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'phones' => [
            '+447700900123',
            '+12025550123',
        ],
        'status' => 'opted_out',
    ],
]);

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

Response 200

{
  "changed": 1,
  "unchanged": 1,
  "invalid": 1
}

GET/v1/consent/history/{phone}

The append-only consent history of one person (the proof of consent).

Path parameters

phonestringrequired
International format +<country code><number> (URL-encode the +); digits only also work. Local numbers use the business country.

Responses

200History
Response fields
- phonestringrequired
- currentobject | nullrequired
- current.chat_idstringrequired
- current.phonestringrequired
  Digits with country code (no +)
- current.statusstringrequired
  One of: opted_in, opted_out
- current.sourcestringrequired
  How the status was set: the customer replied with a keyword, a person in the dashboard, a contacts import with opt_in, an API key, or a privacy erasure
  One of: keyword, manual, import, api, erasure
- current.notestring | nullrequired
- current.created_atintegerrequired
- current.updated_atintegerrequired
- historyarray of objectrequired
- history[].statusstringrequired
  One of: opted_in, opted_out
- history[].sourcestringrequired
- history[].notestring | nullrequired
- history[].atintegerrequired
400INVALID_NUMBER

Request

curl "https://api.chatkomodo.com/v1/consent/history/447700900123" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/consent/history/447700900123', {
  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/consent/history/447700900123",
    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/consent/history/447700900123', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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

Response 200

{
  "phone": "+447700900123",
  "current": {
    "chat_id": "+447700900123",
    "phone": "+447700900123",
    "status": "opted_in",
    "source": "keyword",
    "note": "Prefers delivery after 5 pm",
    "created_at": 1767225600000,
    "updated_at": 1767225600000
  },
  "history": [
    {
      "status": "opted_in",
      "source": "string",
      "note": "Prefers delivery after 5 pm",
      "at": 1767225600000
    }
  ]
}

PUT/v1/consent/{phone}

Opt one person in or out.

Path parameters

phonestringrequired
International format +<country code><number> (URL-encode the +); digits only also work. Local numbers use the business country.

Request body

statusstringrequired
One of: opted_in, opted_out
notestring | null
Up to 200 characters

Responses

200Saved
Response fields
- okbooleanrequired
- changedbooleanrequired
- consentobjectrequired
- consent.chat_idstringrequired
- consent.phonestringrequired
  Digits with country code (no +)
- consent.statusstringrequired
  One of: opted_in, opted_out
- consent.sourcestringrequired
  How the status was set: the customer replied with a keyword, a person in the dashboard, a contacts import with opt_in, an API key, or a privacy erasure
  One of: keyword, manual, import, api, erasure
- consent.notestring | nullrequired
- consent.created_atintegerrequired
- consent.updated_atintegerrequired
400INVALID_NUMBER

Request

curl -X PUT "https://api.chatkomodo.com/v1/consent/447700900123" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "opted_out",
  "note": "Asked to stop by email"
}'

const res = await fetch('https://api.chatkomodo.com/v1/consent/447700900123', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "opted_out",
    "note": "Asked to stop by email"
  }),
});
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/consent/447700900123",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "status": "opted_out",
        "note": "Asked to stop by email",
    },
    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/consent/447700900123', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'status' => 'opted_out',
        'note' => 'Asked to stop by email',
    ],
]);

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

Response 200

{
  "ok": true,
  "changed": true,
  "consent": {
    "chat_id": "+447700900123",
    "phone": "+447700900123",
    "status": "opted_in",
    "source": "keyword",
    "note": "Prefers delivery after 5 pm",
    "created_at": 1767225600000,
    "updated_at": 1767225600000
  }
}

Consent

List consent records

Query parameters

Responses

Get the consent settings

Responses

Update the consent settings

Request body

Responses

Export consent records (CSV)

Responses

Set consent for many numbers

Request body

Responses

Get the consent history of a number

Path parameters

Responses

Opt a number in or out

Path parameters

Request body

Responses