Conversation Hub SDK

import { conversation } from '@runflow-ai/sdk/conversation';

export async function main(input) {
  // Triggered agent: the Conversation Hub fires your HTTP trigger per inbound
  // message (bursts are debounced per conversation).
  const conv = conversation.fromTrigger(input); // reads input.metadata.conversationId

  const { contact, messages, status, humanInLoop } = await conv.get({ messages: 20 });
  await conv.sendText(`Oi ${contact.name}!`);
}

const conv = await conversation.byPhone('+5511999998888', {
  connectionId: 'cn_...', // optional — pin a specific WhatsApp number
  create: true,           // create contact (+ conversation) when missing
});

conv.snapshot;            // resolved state: contact, contactCreated, conversationCreated
await conv.sendTemplate({ name: 'followup', language: 'pt_BR' });

// Free text — only inside Meta's 24h customer-service window
await conv.sendText('Seu pedido saiu para entrega!');

// Outside the window sendText fails with code OUTSIDE_24H_WINDOW — use a template
await conv.sendTemplate({ name: 'order_update', language: 'pt_BR' });

// Media: base64, bytes, or a URL (URLs are downloaded inside the agent process)
await conv.sendMedia({ mediaKind: 'image', url: 'https://cdn.example.com/boleto.png', caption: 'Segue o boleto' });

// Reply buttons (up to 3) and lists
await conv.sendButtons('Confirma o agendamento?', [
  { id: 'yes', title: 'Sim' },
  { id: 'no', title: 'Não' },
]);
await conv.sendInteractive({
  type: 'list',
  body: 'Escolha um horário',
  actionTitle: 'Horários',
  sections: [{ title: 'Amanhã', rows: [{ id: 'h9', title: '09:00' }, { id: 'h14', title: '14:00' }] }],
});

await conv.sendText('Pedido confirmado!', {
  idempotencyKey: `${conv.conversationId}:${input.metadata?.messageId ?? 'reply'}`,
});

await conv.typing();   // "typing..." bubble + marks the last inbound message as read
await conv.markRead(); // blue ticks only

// Queue of a department (by id or exact name)
await conv.transfer({ department: 'Vendas', reason: 'pediu humano', priority: 'HIGH' });

// Straight to a specific attendant (by id or email) — ticket comes pre-assigned
await conv.transfer({ attendant: 'paula@empresa.com', reason: 'cliente VIP' });

// Close the conversation — the AI stops processing new inbound messages
await conv.resolve('caso encerrado');

// Which departments exist?
const departments = await conversation.directory.departments();
// [{ id, name, color, icon, description, members, agents }]

// Who works in Vendas, and how busy are they right now?
const team = await conversation.directory.attendants({ department: 'Vendas' });
// [{ id, name, email, status, load, active, ... }]

const best = team
  .filter((a) => a.active && a.status === 'online')
  .sort((a, b) => a.load - b.load)[0];

await conv.transfer({
  attendant: best?.id,      // undefined → plain department-queue transfer
  department: 'Vendas',
  reason: 'transbordo',
});

import { reply } from '@runflow-ai/sdk/conversation';

return reply('transferindo você para um atendente', { intent: 'escalate' });
// intents: 'escalate' (opens a ticket) · 'resolve' (sends then closes) · 'continue'

// Contacts
const contact = await conversation.contacts.getByPhone('+5511999998888');
await conversation.contacts.update(contact.id, { handlingArea: 'Financeiro' });
await conversation.contacts.create({ name: 'Maria', phone: '+5511988887777', upsert: true });

// Tag a contact (tags are auto-created on first use)
await conversation.contacts.addTag(contact.id, 'vip', '#f59e0b');
await conversation.contacts.removeTag(contact.id, 'inadimplente');

// Tag entity CRUD
const tags = await conversation.tags.list();          // [{ id, name, color, contacts }]
await conversation.tags.create('vip', '#f59e0b');
await conversation.tags.update(tagId, { name: 'VIP' });
await conversation.tags.remove(tagId);                 // also unlinks it from every contact

// Internal notes — show up in the attendant's context panel
await conv.addNote('Cliente pediu boleto até sexta', { agentName: 'Bot Cobrança' });
await conversation.contacts.listNotes(contact.id);
await conversation.contacts.removeNote(contact.id, noteId);

import { ConversationApiError } from '@runflow-ai/sdk/conversation';

try {
  await conv.sendText('...');
} catch (err) {
  if (err instanceof ConversationApiError && err.code === 'OUTSIDE_24H_WINDOW') {
    await conv.sendTemplate({ name: 'reengage' });
  } else {
    throw err;
  }
}