WhatsApp Agent from Scratch

import { createChannelHandler, meta } from '@runflow-ai/sdk/channels';
import { metaHandshake } from './meta-handshake';
import { runTurn } from './agent/runner';

const handler = createChannelHandler({
  provider: meta({
    connector: 'whatsapp-acme',        // your connector instance slug
    phoneNumberId: '123456789012345',  // from WhatsApp → API Setup
  }),
  run: runTurn,
});

export async function main(input: any) {
  // Meta verifies the webhook with a GET before delivering any events.
  // In raw mode the returned string is echoed back as plain text — exactly
  // what Meta's validator expects.
  const challenge = metaHandshake(input);
  if (challenge !== null) return challenge;

  return handler(input);
}

// Meta webhook verification handshake:
//   GET ?hub.mode=subscribe&hub.verify_token=<yours>&hub.challenge=<random>
// Meta expects the bare challenge string back with HTTP 200.

/** Any string you choose — you'll type this SAME value in Meta's webhook config. */
const VERIFY_TOKEN = 'runflow-whatsapp-2026';

function queryParam(
  query: Record<string, unknown>,
  name: string,
): string | undefined {
  const value = query[name];
  if (Array.isArray(value)) {
    return typeof value[0] === 'string' ? value[0] : undefined;
  }
  return typeof value === 'string' ? value : undefined;
}

/**
 * Returns the challenge to echo back when the request is a valid handshake,
 * or `null` when it isn't a handshake at all (a normal webhook event —
 * let the channel handler process it).
 *
 * Throws on a handshake with a wrong verify token, so verification fails
 * loudly instead of silently accepting anyone.
 */
export function metaHandshake(input: {
  request?: { query?: Record<string, unknown> };
}): string | null {
  const query = input?.request?.query;
  if (!query) return null;
  if (queryParam(query, 'hub.mode') !== 'subscribe') return null;

  if (queryParam(query, 'hub.verify_token') !== VERIFY_TOKEN) {
    throw new Error(
      'Meta webhook verification failed: hub.verify_token does not match VERIFY_TOKEN',
    );
  }

  const challenge = queryParam(query, 'hub.challenge');
  if (!challenge) {
    throw new Error('Meta webhook verification failed: hub.challenge missing');
  }
  return challenge;
}

import { Agent } from '@runflow-ai/sdk';
import { openai } from '@runflow-ai/sdk/models';

export const agent = new Agent({
  name: 'whatsapp-assistant',
  instructions: `You are Acme's WhatsApp assistant.
Answer in the user's language. Be brief — this is chat, not email.
If you don't know something, say so instead of guessing.`,
  model: openai('gpt-4o'),
  memory: { maxTurns: 20 },
});

import { reply, type RunTurn } from '@runflow-ai/sdk/channels';
import { agent } from './agent';

export const runTurn: RunTurn = async ({ ctx, events }) => {
  const parts: string[] = [];

  for (const event of events) {
    switch (event.type) {
      case 'text':
        parts.push(event.text);
        break;
      case 'button':
        // The user tapped a quick-reply button — the label is the intent
        parts.push(event.text || event.payload);
        break;
      case 'audio':
        parts.push(
          '[The user sent a voice note. Tell them you cannot listen to audio yet and ask them to type it.]',
        );
        break;
      case 'image':
      case 'video':
      case 'document':
        parts.push(
          event.caption
            ? `[${event.type} received] ${event.caption}`
            : `[${event.type} received]`,
        );
        break;
      case 'location':
        parts.push(`[location] lat ${event.latitude}, lng ${event.longitude}`);
        break;
      default:
        // 'contacts', 'flow-reply', 'unknown' — inspect event.raw when you need them
        break;
    }
  }

  // Nothing actionable in this burst (e.g. only unsupported events): stay silent.
  if (parts.length === 0) return [];

  const result = await agent.process({
    message: parts.join('\n'),
    userId: ctx.userId,     // the sender's WhatsApp number, already normalized
    sessionId: ctx.userId,  // one conversation thread per user
  });

  return [reply.text(result.message)];
};