Labels, automatic labelling and leads

Labels sort your customers: hot-lead, customer, complaint, anything you like. A chat can carry several labels, they are set by hand or by rules, and the same labels drive segments, broadcasts and the leads board. In the dashboard: Labels & automation, the Labels section of a chat in the inbox, and Leads.

One set of labels per person

For a chat with a person, the labels are the labels (tags) of that person's CRM contact, so they are the same on every device and in GET /v1/crm/segments filters and broadcasts. Labelling someone who is not a contact yet saves them as a contact. Group chats keep their own labels. Names are normalised: "Hot Lead" becomes hot-lead; up to 20 per chat.

Add and remove labels

curl -X POST "https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/inbox/447700900123%40s.whatsapp.net/labels" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add": [
    "hot-lead",
    "asks-price"
  ],
  "remove": [
    "cold"
  ]
}'

const res = await fetch('https://api.chatkomodo.com/v1/sessions/YOUR_DEVICE_ID/inbox/447700900123%40s.whatsapp.net/labels', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "add": [
      "hot-lead",
      "asks-price"
    ],
    "remove": [
      "cold"
    ]
  }),
});
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/inbox/447700900123%40s.whatsapp.net/labels",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "add": [
            "hot-lead",
            "asks-price",
        ],
        "remove": [
            "cold",
        ],
    },
    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/inbox/447700900123%40s.whatsapp.net/labels', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'add' => [
            'hot-lead',
            'asks-price',
        ],
        'remove' => [
            'cold',
        ],
    ],
]);

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

Response (shortened)

{
  "labels": [
    {
      "name": "vip",
      "color": "#A2255A"
    },
    {
      "name": "hot-lead",
      "color": "#B23A0E"
    },
    {
      "name": "asks-price",
      "color": "#0E6A7A"
    }
  ],
  "stage": "interested",
  "person": true,
  "history": [
    {
      "label": "asks-price",
      "action": "add",
      "source": "manual",
      "rule_id": null,
      "rule_name": null,
      "actor": "admin",
      "at": 1767225600000
    }
  ]
}

PUT /v1/sessions/{sid}/inbox/{chatId}/labels replaces all labels at once. Colours and descriptions live in the catalogue, GET /v1/labels; renaming a label with PATCH /v1/labels/{name} renames it everywhere.

Automatic labelling

Rules add or remove labels, and can move the person to a lead stage, by themselves:

keyword: an incoming message contains one (or all) of the words. A word also matches longer forms starting with it (harga finds harganya); capitals and accents are ignored.
first_message: the first message of a new chat.
store_event: an order from your connected store (order_created, order_paid, order_shipped, abandoned_checkout).
inactive: no message in the chat for N days (checked hourly).
ai: the AI reads the conversation and decides whether your instruction fits. All AI rules are checked in one call, at most every 15 minutes per chat, and each check uses 1 AI reply of your plan.

An AI rule

curl -X POST "https://api.chatkomodo.com/v1/labels/rules" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ready to buy",
  "trigger": "ai",
  "config": {
    "instruction": "The customer clearly wants to buy or order soon"
  },
  "add_labels": [
    "hot-lead"
  ],
  "remove_labels": [
    "cold"
  ],
  "set_stage": "interested"
}'

const res = await fetch('https://api.chatkomodo.com/v1/labels/rules', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Ready to buy",
    "trigger": "ai",
    "config": {
      "instruction": "The customer clearly wants to buy or order soon"
    },
    "add_labels": [
      "hot-lead"
    ],
    "remove_labels": [
      "cold"
    ],
    "set_stage": "interested"
  }),
});
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/labels/rules",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "name": "Ready to buy",
        "trigger": "ai",
        "config": {
            "instruction": "The customer clearly wants to buy or order soon",
        },
        "add_labels": [
            "hot-lead",
        ],
        "remove_labels": [
            "cold",
        ],
        "set_stage": "interested",
    },
    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/labels/rules', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'name' => 'Ready to buy',
        'trigger' => 'ai',
        'config' => [
            'instruction' => 'The customer clearly wants to buy or order soon',
        ],
        'add_labels' => [
            'hot-lead',
        ],
        'remove_labels' => [
            'cold',
        ],
        'set_stage' => 'interested',
    ],
]);

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

Rules work on chats with a person. People stay in control: a label someone removes by hand is never put back by a rule or the AI for that person (adding it by hand again lifts that), and every change is kept in the chat's history with its source (manual, rule, ai, store).

Leads board

Every person can be in one lead stage. The default stages are New, Contacted, Interested, Won and Lost; set your own (1–12) with PUT /v1/leads/stages. GET /v1/leads returns the board with each person's labels and latest message; move someone with PATCH /v1/leads/{contactId} or PUT /v1/sessions/{sid}/inbox/{chatId}/stage.