Conversation Hub SDK

The Conversation Hub SDK (@runflow-ai/sdk/conversation) lets an agent operate inside the Conversation Hub — Runflow’s WhatsApp/human-in-the-loop console. Answer the conversation that triggered the agent, show a typing indicator, send templates and media, open a ticket for a human attendant, and keep the contact’s profile (tags, internal notes) up to date.

Requires the Conversation Hub feature enabled for your tenant. All calls are authenticated with a tenant-scoped API key; conversations from other tenants return 404 (existence is never leaked).

Setup

One click: with the feature enabled, open Credentials in the Runflow portal, pick Conversation Hub in the credential type dropdown and hit Generate key. The key is minted by the Conversation Hub, stored encrypted as the conversation-api-key credential, and never shown in the browser. Re-running it rotates the key (the previous one is revoked instantly). That’s it — the SDK resolves the key from the credentials store on the first call and talks to the production Conversation Hub by default. Just import the default instance:

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

Getting the conversation

fromTrigger

The conversation that activated this agent — the standard path for triggered agents.

byId

Lazy handle for a known conversation id.

byPhone

Proactive sends — resolve (or create) the thread from a phone number.

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}!`);
}

Proactive flows (cron jobs, external events) usually only know the phone number:

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' });

byPhone matches every stored phone variant (with/without +, with/without the Brazilian mobile 9).

Inbound media

Every inbound media message (audio, image, video, document, sticker) reaches the agent after the Hub downloads it, with a presigned URL (6h TTL) patched into the Meta-shaped envelope — messages[0].audio.link, messages[0].image.link, and so on. Captions are optional; a bare image triggers the agent the same way. Don’t use the accompanying media id: it is Meta’s single-use media id and the Hub’s own download has already consumed it — always read link. Voice notes additionally carry the URL as the trigger’s message body and in metadata.audioUrl, ready for transcription.

Sending messages

// 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' }] }],
});

Interactive messages

sendInteractive covers every interactive type WhatsApp supports. button and list are also composable by attendants in the inbox; the rest are agent-only, because they need ids that live outside the portal (published Flows, catalogs, payment configurations).

Type	What it is	Meta’s limits
`button`	Up to 3 reply buttons	3 buttons, title ≤ 20 chars
`list`	Menu behind a button	10 sections, 10 rows each
`cta_url`	Link button — web catalog, order tracker	label ≤ 20 chars, https only
`copy_code`	One-tap copy — PIX codes, coupons	label ≤ 25 chars
`flow`	Native form (Flow)	CTA ≤ 20 chars
`carousel`	Up to 10 cards, each a `cta_url` with an image	10 cards, no header/footer of its own
`order_details`	Native payment sheet (Native Payments BR)	amounts in cents
`order_status`	Closes the order a payment sheet opened	quotes the original bubble

A body over Meta’s 1024-char limit is not rejected: the Hub sends the excess as leading text bubbles and returns their ids in leadMessageIds, keeping the tail right above the buttons. You never have to pre-chunk.

Every send returns metaMessageId — the wamid an inbound tap, submission or payment will reference through context.id.

// Link button and one-tap copy
await conv.sendCtaUrl('Veja as opções que separei', { displayText: 'Ver catálogo', url: 'https://loja.exemplo/catalogo' });
await conv.sendCopyCode('*PIX gerado!*', { displayText: 'Copiar código Pix', code: '00020126580014BR.GOV.BCB.PIX...' });

Flow (native form)

flowToken is yours. It travels to Meta untouched and comes back inside the submission (nfm_reply → response_json), so it is what correlates an answer with the context that asked for it — an order id, a checkout attempt, a profile edit.

await conv.sendInteractive({
  type: 'flow',
  body: 'Preenche rapidinho aí 👇',
  header: 'Cadastro',
  footer: 'Leva 1 minuto',
  action: {
    flowId: '1234567890',          // Flow published on the WABA
    flowToken: `cadastro:${conv.conversationId}`,
    cta: 'Abrir formulário',
    screen: 'CADASTRO',            // omit for a data_exchange Flow
    data: { nome: 'Ana', email: 'ana@exemplo.com' },
  },
});

screen picks the entry point: with it the message navigates to that screen and data prefills it; without it the Flow resolves its first screen on your Flow endpoint (data_exchange), and sending data is an error. Use mode: 'draft' to render a Flow that is not published yet.

Carousel

await conv.sendCarousel('Escolhi 3 opções com seu crédito 🎁', [
  {
    imageUrl: 'https://cdn.exemplo/girassol.jpg',
    body: 'Arranjo Girassol — R$ 269,00',
    ctaUrl: { displayText: 'Quero esse', url: 'https://loja.exemplo/girassol' },
  },
  // ...up to 10
]);

Carousels outside a template are not part of Meta’s stable Cloud API surface. The Hub sends exactly the documented payload; if your WABA rejects it, the Graph error lands in the message’s failReason and shows up in the inbox. Smoke-test it on your own number before a flow depends on it.

Payments (order_details / order_status)

Every amount is an integer in cents, and totalAmount has to equal subtotal + tax + shipping − discount — the Hub rejects the send with a 400 when it doesn’t, which reads far better than Meta’s own error. Who owns the charge is a choice — exactly one of the two, never both:

paymentConfiguration — a payment configuration registered on your WABA; Meta/your PSP generates the charge.
pixDynamicCode — an inline PIX charge your backend generated ({ code, merchantName, key, keyType }, where code is the EMV “copia e cola” payload). Use it when the charge id, expiry and reconciliation live on your side.

// Variant 1 — WABA-registered configuration (Meta/PSP owns the charge)
const order = await conv.sendOrderDetails('Revise e pague', {
  referenceId: 'PED-1042',
  paymentConfiguration: 'minha-config-br',
  items: [{ retailerId: 'SKU-1', name: 'Arranjo Girassol', quantity: 1, amount: 26900 }],
  subtotal: 26900,
  shipping: 1500,
  totalAmount: 28400,
});

// Variant 2 — inline PIX generated by your backend
await conv.sendOrderDetails('Revise e pague', {
  referenceId: chargeId,
  pixDynamicCode: {
    code: emvPayload,            // EMV "copia e cola" from your PSP/backend
    merchantName: 'Minha Loja',
    key: 'a1b2c3d4-…',
    keyType: 'EVP',              // CPF | CNPJ | EMAIL | PHONE | EVP
  },
  items: [{ retailerId: chargeId, name: 'Arranjo Girassol', quantity: 1, amount: 26900 }],
  subtotal: 26900,
  totalAmount: 26900,
});

// Depois da confirmação: sem isso o pedido fica "pendente" para sempre.
await conv.sendOrderStatus('Pagamento confirmado!', {
  referenceId: 'PED-1042',
  status: 'completed',
  replyToMetaMessageId: order.metaMessageId!, // a bolha da cobrança
});

Safe retries (idempotency)

Every send accepts an idempotencyKey. Retrying with the same key returns the original message instead of double-sending — the reply carries deduplicated: true.

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

Typing indicator & read receipts

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

Both anchor on the contact’s last inbound message (Meta requires it), so they return 422 on a conversation with no inbound yet. The typing bubble auto-dismisses in ~25s or when your reply arrives — call typing() right when the trigger fires, before slow work.

Handoff & resolution

transfer opens a ticket in the attendants’ queue and flips the conversation out of AI mode. resolve closes the case.

// 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');

Choosing where to hand off

conversation.directory is a read-only view of your workspace’s service structure — the departments and the attendants (human agents) registered in the Conversation Hub. Use it when the agent needs to decide the transfer target at runtime instead of hard-coding a department name.

// 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, ... }]

Each attendant carries two live signals: status (presence: online / busy / away / offline) and load (how many human conversations they are handling at this moment). A common pattern — route to the least-busy online attendant, falling back to the department queue when nobody is available:

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',
});

Legacy sync agents

Agents invoked through the direct execution endpoint (no HTTP trigger) answer with the reply helper — intent drives the handoff:

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, tags & notes

// 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);

Agent-authored notes have no human author — the portal shows the agentName label (default: Agente AI).

Custom fields (metadata)

Contacts carry a flat metadata object — key/value pairs for whatever your domain needs (CPF, birth date, plan, consent flags). Both create and update accept it:

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

await conversation.contacts.create({
  name: 'Maria',
  phone: '+5511988887777',
  upsert: true, // on an existing contact, metadata is MERGED in — never replaced
  metadata: { cpf: '12345678900', nascimento: '1990-05-12' },
});

// Partial update: only the keys you send change
await conversation.contacts.update(contact.id, {
  metadata: { plano: 'premium', nascimento: null }, // null removes the key
});

const maria = await conversation.contacts.getByPhone('+5511988887777');
maria.metadata; // { cpf: '12345678900', plano: 'premium' }

Write semantics — shallow partial merge:

A write only touches the keys it mentions; every other key stays as-is.
Sending null for a key removes it.
On create with upsert: true, metadata is merged into the existing contact’s metadata (it never wipes what’s already there).

Limits:

Rule	Value
Value types	Scalars only — `string`, `number`, `boolean`, `null` (no objects or arrays)
Key format	`^[a-z0-9_]{1,64}$`
Keys per contact	50 max
String value length	1,024 chars max

contact.metadata comes back on every read that returns a contact — contacts.getByPhone and conv.get().contact. The value type is exported as ContactMetadata from @runflow-ai/sdk/conversation (re-exported from the SDK root as ConversationContactMetadata).

Metadata is strictly per contact — there is no shared field schema. A key written on one contact exists only on that contact; the portal renders whatever keys each contact carries, and any key matching the rules above is accepted.

Metadata in the inbox

The fields your agent writes are not just storage — they surface in the attendants’ console. Each contact’s keys render on their profile and on the inbox side panel, and the inbox can filter conversations by connection (which WhatsApp number the thread lives on), by agent, and by custom field — the attendant types any key and value, and the filter does a case-insensitive partial match on that key’s value. Pull up, say, every conversation whose contact has plano containing premium on the sales number. These filters are a portal feature. The agent API does not expose filtered conversation listing — from agent code you reach conversations through fromTrigger, byId and byPhone.

Error handling

API failures throw ConversationApiError with status, a typed code when available, and the raw body:

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;
  }
}

Common codes: OUTSIDE_24H_WINDOW (free-form send outside Meta’s window), CONTACT_NOT_FOUND / CONVERSATION_NOT_FOUND (byPhone without create), CONNECTION_NOT_FOUND (unknown connectionId).

Status callbacks

Meta reports what happened to every message you sent — delivered, read, failed. The Hub always consumes those: the ticks move in the inbox and the message row gets its status either way. Forwarding them to the agent is opt-in, because each callback becomes one agent execution — a 1,000-message campaign can mean a few thousand runs. Turn it on only for flows that actually track delivery (a reminder that escalates when it goes unread, for instance).

In the Runflow portal: Agents → configure the agent → Encaminhar entregas/leituras, where each agent inherits the organization default or overrides it. The organization-wide value lives in Settings → Recursos (admins only).

When it is on, the agent is triggered with an empty message, metadata.kind = 'status' and the raw Meta status payload — the same wamid your send returned as metaMessageId.

API surface

Handle (`conv`)	Hub (`conversation`)
`get({ messages? })`	`fromTrigger(input)` · `byId(id)` · `byPhone(phone, opts?)`
`sendText` · `sendTemplate` · `sendMedia` · `sendButtons` · `sendInteractive`	`contacts.*` — create, getByPhone, update (create/update accept `metadata`), addTag, removeTag, addNote, listNotes, removeNote
`sendCtaUrl` · `sendCopyCode` · `sendFlow` · `sendCarousel` · `sendOrderDetails` · `sendOrderStatus`
`typing()` · `markRead()`	`tags.*` — list, create, update, remove
`transfer(opts?)` · `resolve(reason?)`	`directory.departments()` · `directory.attendants({ department? })`
`addNote(text, { agentName? })`	`reply(message, { intent?, metadata? })` (sync path)

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Conversation Hub SDK

Setup

Getting the conversation

fromTrigger

byId

byPhone

Inbound media

Sending messages

Interactive messages

Flow (native form)

Carousel

Payments (order_details / order_status)

Safe retries (idempotency)

Typing indicator & read receipts

Handoff & resolution

Choosing where to hand off

Legacy sync agents

Contacts, tags & notes

Custom fields (metadata)

Metadata in the inbox

Error handling

Status callbacks

API surface

​Setup

​Getting the conversation

fromTrigger

byId

byPhone

​Inbound media

​Sending messages

​Interactive messages

​Flow (native form)

​Carousel

​Payments (order_details / order_status)

​Safe retries (idempotency)

​Typing indicator & read receipts

​Handoff & resolution

​Choosing where to hand off

​Legacy sync agents

​Contacts, tags & notes

​Custom fields (metadata)

​Metadata in the inbox

​Error handling

​Status callbacks

​API surface

Setup

Getting the conversation

Inbound media

Sending messages

Interactive messages

Flow (native form)

Carousel

Payments (order_details / order_status)

Safe retries (idempotency)

Typing indicator & read receipts

Handoff & resolution

Choosing where to hand off

Legacy sync agents

Contacts, tags & notes

Custom fields (metadata)

Metadata in the inbox

Error handling

Status callbacks

API surface