fastify-x-twilio

conversations.*

Manage Twilio Conversations — create threads, add participants, send messages, and configure webhooks.

conversations.*

Full lifecycle management for Twilio Conversations — multi-channel message threads that can include SMS, MMS, WhatsApp, and chat participants.

Signatures

fastify.conversations.create(friendlyName: string, attributes?: object): Promise<Object>
fastify.conversations.get(conversationSid: string): Promise<Object>
fastify.conversations.update(conversationSid: string, updates: object): Promise<Object>
fastify.conversations.list(filters?: { limit?: number }): Promise<Object[]>
fastify.conversations.delete(conversationSid: string): Promise<true>

fastify.conversations.addParticipant(conversationSid: string, identity?: string, messagingBindingAddress?: string): Promise<Object>
fastify.conversations.listParticipants(conversationSid: string): Promise<Object[]>
fastify.conversations.removeParticipant(conversationSid: string, participantSid: string): Promise<true>

fastify.conversations.sendMessage(conversationSid: string, body: string, author?: string, attributes?: object): Promise<Object>
fastify.conversations.sendMediaMessage(conversationSid: string, mediaUrl: string, body?: string, author?: string): Promise<Object>
fastify.conversations.getMessages(conversationSid: string, options?: { limit?: number; order?: string }): Promise<Object[]>
fastify.conversations.getMessage(conversationSid: string, messageSid: string): Promise<Object>
fastify.conversations.deleteMessage(conversationSid: string, messageSid: string): Promise<true>

fastify.conversations.getWebhooks(conversationSid: string): Promise<Object[]>
fastify.conversations.createWebhook(conversationSid: string, webhookConfig: object): Promise<Object>

Params

Conversation management

Method	Key Params
`create(friendlyName, attributes?)`	`friendlyName` — display name for the conversation.
`get(conversationSid)`	Fetch a conversation by SID.
`update(conversationSid, updates)`	Partial update; `updates` is the fields to change.
`list(filters?)`	`filters.limit` defaults to `50`.
`delete(conversationSid)`	Returns `true` on success.

Participant management

Method	Key Params
`addParticipant(conversationSid, identity?, messagingBindingAddress?)`	Supply `identity` for chat users or `messagingBindingAddress` (E.164 phone) for SMS participants. At least one required.
`listParticipants(conversationSid)`	Returns all participants in the conversation.
`removeParticipant(conversationSid, participantSid)`	`participantSid` is from `addParticipant` or `listParticipants`.

Message management

Method	Key Params
`sendMessage(conversationSid, body, author?, attributes?)`	`author` sets display name. `attributes` is stringified to JSON.
`sendMediaMessage(conversationSid, mediaUrl, body?, author?)`	`mediaUrl` is required. `body` optional caption.
`getMessages(conversationSid, options?)`	`options.limit` defaults to `50`; `options.order` defaults to `"desc"`.
`getMessage(conversationSid, messageSid)`	Fetch a specific message.
`deleteMessage(conversationSid, messageSid)`	Returns `true` on success.

Webhook management

Method	Key Params
`getWebhooks(conversationSid)`	List all webhooks on a conversation.
`createWebhook(conversationSid, webhookConfig)`	`webhookConfig` follows the Twilio Conversations webhook API shape.

Examples

Create a conversation and add participants

const conv = await fastify.conversations.create("Support Chat #4321");

// Add a chat participant (by identity)
await fastify.conversations.addParticipant(conv.sid, "user-456");

// Add an SMS participant (by phone number)
await fastify.conversations.addParticipant(conv.sid, null, "+15551234567");

Send a message and list history

await fastify.conversations.sendMessage(
  "CHxxxx",
  "Hi! How can I help you today?",
  "SupportBot"
);

const messages = await fastify.conversations.getMessages("CHxxxx", { limit: 20 });
messages.forEach((m) => console.log(`[${m.author}]: ${m.body}`));

Realistic — live chat support thread

fastify.post("/support/conversations", async (request, reply) => {
  const { userId, phoneNumber } = request.body;

  const conv = await fastify.conversations.create(`Support - ${userId}`);

  // Add customer as SMS participant
  await fastify.conversations.addParticipant(conv.sid, null, phoneNumber);

  // Send welcome message
  await fastify.conversations.sendMessage(
    conv.sid,
    "Welcome to support! An agent will be with you shortly.",
    "System"
  );

  await db.supportTickets.create({
    userId,
    conversationSid: conv.sid,
    status: "open",
  });

  return reply.code(201).send({ conversationSid: conv.sid });
});

createWebhook — receive events for a conversation

const webhook = await fastify.conversations.createWebhook("CHxxxx", {
  target: "webhook",
  configuration: {
    url: "https://api.example.com/webhooks/twilio/conversations",
    method: "POST",
    filters: ["onMessageAdded", "onParticipantAdded"],
  },
});

Throws

[xTwilio] conversations.create: friendlyName (string) is required
[xTwilio] conversations.get: conversationSid (string) is required
[xTwilio] conversations.update: updates (object) is required
[xTwilio] conversations.addParticipant: either identity or messagingBindingAddress is required
[xTwilio] conversations.sendMessage: body (string) is required
[xTwilio] conversations.sendMediaMessage: mediaUrl (string) is required
[xTwilio] conversations.createWebhook: webhookConfig (object) is required
[xTwilio] Failed to <action>: <message> — Twilio API error

AI Context

package: "@xenterprises/fastify-xtwilio"
decorator: fastify.conversations
methods: create, get, update, list, delete, addParticipant, listParticipants, removeParticipant, sendMessage, sendMediaMessage, getMessages, getMessage, deleteMessage, getWebhooks, createWebhook
use-when: Multi-channel messaging threads via Twilio Conversations API

Edit this pageorReport an issue

fastify-x-twilio

Fastify plugin for Twilio communications (SMS, MMS, Conversations, RCS) and SendGrid email — 48 methods across 4 service decorators.

email.validate / email.addContact / email.searchContact / email.deleteContact / email.createList / email.getLists / email.deleteList

Validate email addresses and manage SendGrid marketing contacts and lists.