Guía · chat:write

Bot de chat de atención al cliente

Responde a las personas que escriben a tu cuenta: preguntas sobre pedidos, horarios, preguntas frecuentes. Pasa la conversación a una persona cuando sea necesario.

Scopes: chat:read, chat:write (opcional: orders:read para consultar pedidos).

La regla antispam#

Un bot solo puede escribir donde la otra persona ya ha escrito, o a personas que siguen la cuenta. Cualquier otro caso falla con 403 CHAT_NOT_ALLOWED. Los bloqueos se aplican siempre (403 CHAT_BLOCKED). Así, los bots de soporte son fáciles de crear y los contactos en frío son imposibles, por diseño.

Los endpoints#

Endpoint	Uso
GET `/conversations`	Tus conversaciones, empezando por la actividad más reciente (paginado).
GET `/conversations/{id}/messages`	Mensajes de una conversación, del más reciente al más antiguo (paginado).
POST `/conversations/{id}/messages`	Responde en una conversación existente.
POST `/messages`	Escribe a un usuario por su id (abre la conversación si es necesario). Sujeto a la regla antispam.

1. Busca conversaciones a las que responder#

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

En cada conversación con actividad nueva, lee los últimos mensajes y comprueba quién escribió el último: si no fuiste tú, puede que el bot tenga algo que responder.

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

2. Responde#

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. Un bot de polling completo#

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)

Los nombres de campo como senderId se muestran a modo de ejemplo: consulta el esquema del mensaje en la Referencia de la API.

Polling responsable#

Consulta cada 15–60 segundos. Una llamada a /conversations más unas pocas lecturas de mensajes por ciclo se mantiene muy por debajo de 120 solicitudes por minuto.
Abre solo las conversaciones cuya última actividad haya cambiado desde el ciclo anterior.
La cuota diaria es de 500 mensajes por cuenta.

Sé un buen bot#

Indica que eres un bot en la primera respuesta y explica cómo contactar con una persona.
Nunca envíes promociones a quien no las ha pedido, ni el mismo mensaje a muchas personas.
No pidas contraseñas, datos de pago ni códigos por chat.
Deja de escribir cuando te lo pidan.