Guide · chat:write

Customer-support chat bot

Answer the people who write to your account: order questions, opening hours, FAQs. Hand over to a human when needed.

Scopes: chat:read, chat:write (optional: orders:read to look up orders).

The anti-spam rule#

A bot can write only where the other person has already written, or to people who follow the account. Anything else fails with 403 CHAT_NOT_ALLOWED. Blocks always apply (403 CHAT_BLOCKED). This makes support bots easy and cold outreach impossible — by design.

The endpoints#

Endpoint	Use
GET `/conversations`	Your conversations, most recent activity first (paginated).
GET `/conversations/{id}/messages`	Messages of a conversation, newest first (paginated).
POST `/conversations/{id}/messages`	Reply in an existing conversation.
POST `/messages`	Write to a user by id (opens the conversation if needed). Subject to the anti-spam rule.

1. Find conversations to answer#

curl "https://api.linework.app/open/v1/conversations?limit=20" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

For each conversation with new activity, read the latest messages and check who wrote last: if it is not you, the bot may have something to answer.

curl "https://api.linework.app/open/v1/conversations/c_3391/messages?limit=10" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

2. Reply#

curl https://api.linework.app/open/v1/conversations/c_3391/messages \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hi! We are open Monday to Saturday, 9:00–19:00." }'

3. A complete polling bot#

const API = "https://api.linework.app/open/v1";
const headers = { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`, "Content-Type": "application/json" };
const get = (p) => fetch(API + p, { headers }).then((r) => r.json());

const me = await get("/me");
const answered = new Set(); // in production: a database

async function tick() {
  const convs = await get("/conversations?limit=20");
  for (const conv of convs.data) {
    const msgs = await get(`/conversations/${conv.id}/messages?limit=5`);
    const last = msgs.data[0]; // newest first
    if (!last || last.senderId === me.id || answered.has(last.id)) continue;

    const reply = answer(last.text);
    answered.add(last.id);
    if (!reply) continue; // a human will answer

    const res = await fetch(`${API}/conversations/${conv.id}/messages`, {
      method: "POST", headers, body: JSON.stringify({ text: reply }),
    });
    if (res.status === 429) return; // quota or rate limit: try again later
  }
}

function answer(text = "") {
  if (/hours|open|orari/i.test(text)) return "We are open Monday to Saturday, 9:00–19:00.";
  if (/order|ordine/i.test(text)) return "Send me your order number and I will check it for you.";
  return null;
}

setInterval(() => tick().catch(console.error), 30_000);

import os, re, time, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

me = s.get(API + "/me", timeout=30).json()
answered = set()  # in production: a database

def answer(text):
    if re.search(r"hours|open|orari", text or "", re.I):
        return "We are open Monday to Saturday, 9:00–19:00."
    if re.search(r"order|ordine", text or "", re.I):
        return "Send me your order number and I will check it for you."
    return None

def tick():
    convs = s.get(API + "/conversations", params={"limit": 20}, timeout=30).json()
    for conv in convs["data"]:
        msgs = s.get(f"{API}/conversations/{conv['id']}/messages", params={"limit": 5}, timeout=30).json()
        last = msgs["data"][0] if msgs["data"] else None  # newest first
        if not last or last["senderId"] == me["id"] or last["id"] in answered:
            continue
        answered.add(last["id"])
        reply = answer(last.get("text"))
        if not reply:
            continue  # a human will answer
        r = s.post(f"{API}/conversations/{conv['id']}/messages", json={"text": reply}, timeout=30)
        if r.status_code == 429:
            return  # quota or rate limit: try again later

while True:
    tick()
    time.sleep(30)

Field names such as senderId are shown for illustration: check the message schema in the API Reference.

Polling politely#

Poll every 15–60 seconds. One /conversations call plus a few message reads per tick stays far below 120 requests per minute.
Only open conversations whose last activity changed since the previous tick.
The daily quota is 500 messages per account.

Be a good bot#

Say it is a bot in the first reply, and tell people how to reach a human.
Never send promotions to people who did not ask, and never send the same message to many people.
Do not ask for passwords, payment details or codes in chat.
Stop when people ask you to stop.