ChatKomodo Docs Home Sign in

API reference · Conversations

Auto-reply rules

Keyword rules that answer incoming messages per device (exact, contains, regex), with cooldowns.

List auto-reply rules

GET/v1/sessions/{sessionId}/auto-reply

List auto-reply rules for a session.

Path parameters

  • sessionIdstringrequired

Responses

  • 200List of rules
    Response fields
    • rulesarray of objectrequired
    • rules[].idstringrequired
    • rules[].session_idstringrequired
    • rules[].namestringrequired
    • rules[].trigger_typestringrequired
      any replies to every message; keyword matches the whole text; contains matches a word or phrase inside it; regex uses trigger_text as a regular expression
      One of: any, keyword, contains, regex
    • rules[].trigger_textstring | nullrequired
      Text or regular expression to compare with; unused by any
    • rules[].match_caseintegerrequired
      1 = case-sensitive, 0 = not
    • rules[].reply_typestringrequired
      One of: text, image, document, audio, video, sticker
    • rules[].reply_bodystring | nullrequired
      Reply text. Supports the personalization tokens {name}, {first_name}, {phone} and {{first_name|there}}-style fallbacks
    • rules[].reply_r2_keystring | nullrequired
      Media key for non-text replies
    • rules[].reply_captionstring | nullrequired
    • rules[].cooldown_msintegerrequired
      Minimum time before the same chat gets this rule again
    • rules[].priorityintegerrequired
      Higher runs first
    • rules[].is_activeintegerrequired
      1 or 0
    • rules[].created_atintegerrequired
Request
curl "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply', {
  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/auto-reply",
    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/auto-reply', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 200
{
  "rules": [
    {
      "id": "01JA5V6Q8M2H7G4K9P3T0R1S2X",
      "session_id": "YOUR_DEVICE_ID",
      "name": "Opening hours",
      "trigger_type": "any",
      "trigger_text": "price",
      "match_case": 1,
      "reply_type": "text",
      "reply_body": "Hi Sam, your order has shipped.",
      "reply_r2_key": "Hi Sam, your order has shipped.",
      "reply_caption": "Hi Sam, your order has shipped.",
      "cooldown_ms": 1767225600000,
      "priority": 1,
      "is_active": 1,
      "created_at": 1767225600000
    }
  ]
}

Create an auto-reply rule

POST/v1/sessions/{sessionId}/auto-reply

Adds a rule that answers inbound messages of this session. Only the first matching active rule answers, and only chats that are not groups, channels or Status. Booleans accept true/false, 1/0 and the strings "true", "false", "1", "0".

Path parameters

  • sessionIdstringrequired
    Session (device) id

Request body

  • namestringrequired
    Rule name
    1–100 characters
  • trigger_typestringrequired
    any: every inbound message; keyword: the whole message equals trigger_text; contains: the message contains trigger_text; regex: the message matches the regular expression in trigger_text (rejected as UNSAFE_REGEX when it could backtrack catastrophically)
    One of: any, keyword, contains, regex
  • trigger_textstring | null
    Text or regular expression to compare with; unused by any
    Up to 500 characters
  • match_caseboolean | number | string
    Case-sensitive matching (default false)
  • reply_typestring
    Default text
    One of: text, image, document, audio, video, sticker
  • reply_bodystring | null
    Reply text; personalization tokens such as {first_name} or {{first_name|there}} are filled from the CRM
    Up to 4 096 characters
  • reply_r2_keystring | null
    Media key from /v1/media/upload-url for non-text replies
    Up to 256 characters
  • reply_captionstring | null
    Caption of a media reply (tokens are filled like in reply_body)
    Up to 1 024 characters
  • cooldown_msinteger
    Minimum time before this rule answers the same chat again (default 60 000)
    From 0 to 2 592 000 000
  • priorityinteger
    Rules are tried from the highest priority down; the first match answers (default 0)
    From -10 000 to 10 000
  • is_activeboolean | number | string
    Inactive rules never fire (default true)

Responses

  • 201Rule created
    Response fields
    • idstringrequired
      Rule id
  • 400Invalid body (VALIDATION_FAILED, INVALID_JSON) or an unsafe regular expression (UNSAFE_REGEX)
  • 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/auto-reply" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Opening hours",
  "trigger_type": "contains",
  "trigger_text": "open",
  "reply_type": "text",
  "reply_body": "We are open Monday to Saturday, 9:00–17:00.",
  "cooldown_ms": 3600000
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Opening hours",
    "trigger_type": "contains",
    "trigger_text": "open",
    "reply_type": "text",
    "reply_body": "We are open Monday to Saturday, 9:00–17:00.",
    "cooldown_ms": 3600000
  }),
});
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/auto-reply",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "name": "Opening hours",
        "trigger_type": "contains",
        "trigger_text": "open",
        "reply_type": "text",
        "reply_body": "We are open Monday to Saturday, 9:00–17:00.",
        "cooldown_ms": 3600000,
    },
    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/auto-reply', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'name' => 'Opening hours',
        'trigger_type' => 'contains',
        'trigger_text' => 'open',
        'reply_type' => 'text',
        'reply_body' => 'We are open Monday to Saturday, 9:00–17:00.',
        'cooldown_ms' => 3600000,
    ],
]);

print_r(json_decode((string) $res->getBody(), true));
Response 201
{
  "id": "01JA5V6Q8M2H7G4K9P3T0R1S2X"
}

Update an auto-reply rule

PATCH/v1/sessions/{sessionId}/auto-reply/{ruleId}

Changes the given fields of a rule; omitted fields keep their value. The resulting regular expression is re-checked when the rule is or becomes a regex rule.

Path parameters

  • sessionIdstringrequired
    Session (device) id
  • ruleIdstringrequired
    Rule id

Request body

  • namestring
    Rule name
    1–100 characters
  • trigger_typestring
    any: every inbound message; keyword: the whole message equals trigger_text; contains: the message contains trigger_text; regex: the message matches the regular expression in trigger_text (rejected as UNSAFE_REGEX when it could backtrack catastrophically)
    One of: any, keyword, contains, regex
  • trigger_textstring | null
    Text or regular expression to compare with; unused by any
    Up to 500 characters
  • match_caseboolean | number | string
    Case-sensitive matching (default false)
  • reply_typestring
    Default text
    One of: text, image, document, audio, video, sticker
  • reply_bodystring | null
    Reply text; personalization tokens such as {first_name} or {{first_name|there}} are filled from the CRM
    Up to 4 096 characters
  • reply_r2_keystring | null
    Media key from /v1/media/upload-url for non-text replies
    Up to 256 characters
  • reply_captionstring | null
    Caption of a media reply (tokens are filled like in reply_body)
    Up to 1 024 characters
  • cooldown_msinteger
    Minimum time before this rule answers the same chat again (default 60 000)
    From 0 to 2 592 000 000
  • priorityinteger
    Rules are tried from the highest priority down; the first match answers (default 0)
    From -10 000 to 10 000
  • is_activeboolean | number | string
    Inactive rules never fire (default true)

Responses

  • 200Updated
    Response fields
    • okbooleanrequired
  • 400Invalid body (VALIDATION_FAILED, INVALID_JSON) or an unsafe regular expression (UNSAFE_REGEX)
  • 401Missing or invalid credentials
  • 403The API key is restricted to other sessions, or the operation is not available to CS-agent logins
  • 404Rule not found (NOT_FOUND); unknown session, or a session of another tenant
Request
curl -X PATCH "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reply_body": "We are open Monday to Saturday, 9:00–18:00."
}'
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reply_body": "We are open Monday to Saturday, 9:00–18: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.patch(
    "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "reply_body": "We are open Monday to Saturday, 9:00–18:00.",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PATCH', 'https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'reply_body' => 'We are open Monday to Saturday, 9:00–18:00.',
    ],
]);

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

Delete an auto-reply rule

DEL/v1/sessions/{sessionId}/auto-reply/{ruleId}

Deletes the rule and its per-chat cooldown records.

Path parameters

  • sessionIdstringrequired
    Session (device) id
  • ruleIdstringrequired
    Rule id

Responses

  • 200Deleted
    Response fields
    • okbooleanrequired
  • 401Missing or invalid credentials
  • 403The API key is restricted to other sessions, or the operation is not available to CS-agent logins
  • 404Rule not found (NOT_FOUND); unknown session, or a session of another tenant
Request
curl -X DELETE "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"
const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/auto-reply/RULE_ID', {
  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/auto-reply/RULE_ID",
    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/auto-reply/RULE_ID', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

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