Conecta tu bot de WhatsApp

WhatsApp queda fuera de Orkestra: tu empresa sigue con su cuenta de WhatsApp Business y su propio bot. Esta guía muestra cómo ese bot crea tareas en Orkestra y se entera de lo que cambia, usando un token personal y los webhooks.

Cómo encaja

Orkestra no envía ni recibe mensajes de WhatsApp, y nunca los paga. Tu bot sí: es un programa tuyo que habla con WhatsApp por su lado y con Orkestra por el otro.

  • Del bot a Orkestra: el bot usa la API REST con un token personal para crear una tarea, comentarla o moverla de columna.
  • De Orkestra al bot: el bot recibe un webhook cuando algo cambia, y desde su cuenta de WhatsApp le avisa a quien corresponda.

Los fragmentos de abajo son solo ejemplos para que armes el tuyo. No son código de Orkestra ni un plugin, y están en Node.js solo por elegir uno: sirve cualquier lenguaje.

Una cuenta para el bot

Dale al bot su propia cuenta de miembro, con el rol y las áreas que necesita y nada más. Así lo que hace queda firmado con su nombre en el historial, y un token nunca puede más que la cuenta que lo creó.

  1. Invita a esa cuenta a tu organización y ponle el rol y el área que le tocan.
  2. Entrando con ella, crea un token en Tus ajustes → Conexiones con IA. Elige la API REST, escritura en tareas y proyectos, y limítalo a tu organización.
  3. Guarda la clave ork_…: se muestra una sola vez.

El token tiene 1000 pedidos cada 15 minutos. Para enterarte de cambios, escucha webhooks en vez de consultar la API cada tanto.

Crear una tarea desde un mensaje

Cuando llega un pedido por WhatsApp, el bot crea una tarea en el proyecto que corresponda:

const API = 'https://api.orkestra.team/api/v1';

async function crearTarea(projectId, titulo, descripcion) {
  const res = await fetch(`${API}/projects/${projectId}/tasks`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ORKESTRA_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ title: titulo, description: descripcion, priority: 'MEDIUM' }),
  });
  const { data } = await res.json();
  return data;
}

Si ya tienes la ficha del cliente en Contactos, la tarea acepta clientId para dejarla asociada a esa ficha. Para encontrarla, busca por el teléfono con el que escribió, tal como llegó de WhatsApp (con +, espacios o guiones, da igual):

async function buscarContacto(orgId, telefono) {
  const res = await fetch(
    `${API}/organizations/${orgId}/agency/clients?phone=${encodeURIComponent(telefono)}`,
    { headers: { Authorization: `Bearer ${process.env.ORKESTRA_TOKEN}` } },
  );
  const { data } = await res.json();
  return data; // varias fichas pueden compartir un número
}

Con la ficha encontrada, crea la tarea con su clientId. La búsqueda necesita al menos 4 dígitos y solo devuelve las fichas que tu token puede ver.

Para sumar lo que el cliente escribe después, comenta la tarea: POST /tasks/:id/comments con { "content": "…" }. Para pasarla de columna, POST /tasks/:id/move con { "stateId": "…" }.

Recibir un webhook

En Ajustes de la organización → Conexiones → Webhooks crea un webhook con la dirección pública de tu bot y suscríbelo a estos eventos:

  • task.moved: la tarea cambió de columna (fromState y toState).
  • task.assigned: alguien quedó asignado (addedAssigneeIds).
  • task.overdue: el vencimiento pasó y la tarea sigue abierta.

Un webhook que no eligió proyectos envía solo los que ve toda la organización. Si tus pedidos viven en un proyecto privado o de un área, elígelo en el webhook (ver Qué proyectos envía).

Cada entrega es un POST con un JSON como este:

{
  "event": "task.moved",
  "timestamp": "2026-10-20T14:03:11.000Z",
  "organizationId": "…",
  "data": { "projectId": "…", "task": { "id": "…", "title": "…" } }
}

Verificar la firma

Cada entrega trae el header X-Orkestra-Signature: el HMAC-SHA256, en hexadecimal, del cuerpo crudo con el secreto de tu webhook. Verifícalo antes de creer en el mensaje. Con Express, el cuerpo hay que leerlo crudo, sin parsear:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/orkestra', express.raw({ type: 'application/json' }), (req, res) => {
  const esperado = crypto
    .createHmac('sha256', process.env.ORKESTRA_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const recibido = String(req.get('X-Orkestra-Signature') ?? '');

  const a = Buffer.from(esperado);
  const b = Buffer.from(recibido);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const evento = JSON.parse(req.body.toString('utf8'));
  // Aquí le avisas al cliente por WhatsApp, con tu propio bot.
  console.log(evento.event, evento.data.task?.title);
  res.sendStatus(200);
});

app.listen(3000);

Responde con un 2xx rápido: ante un 5xx o un tiempo agotado Orkestra reintenta, y ante un 4xx no.

Qué queda de tu lado

El número de WhatsApp, el proveedor del bot, los mensajes y lo que cuesten son tuyos. Orkestra solo pone las tareas, la API y los webhooks.