@convex-dev/twilio
v0.1.4
Published
Convex component for sending/receiving SMS messages with Twilio.
Downloads
76
Readme
Convex Twilio Component
Note: Convex Components are currently in beta.
Send and receive SMS messages in your Convex app using Twilio.
import { Twilio } from "@convex-dev/twilio";
import { components } from "./_generated/api";
export const twilio = new Twilio(components.twilio, {
defaultFrom: process.env.TWILIO_PHONE_NUMBER!,
});
export const sendSms = internalAction({
handler: async (ctx, args) => {
return await twilio.sendMessage(ctx, {
to: "+14151234567",
body: "Hello, world!",
});
},
});
Prerequisites
Twilio Phone Number
Create a Twilio account and, if you haven't already, create a Twilio Phone Number.
Note the Phone Number SID of the phone number you'll be using, you'll need it in a moment.
Convex App
You'll need a Convex App to use the component. Follow any of the Convex quickstarts to set one up.
Installation
Install the component package:
npm install @convex-dev/twilio
Create a convex.config.ts
file in your app's convex/
folder and install the component by calling use
:
// convex/convex.config.ts
import { defineApp } from "convex/server";
import twilio from "@convex-dev/twilio/convex.config";
const app = defineApp();
app.use(twilio);
export default app;
Set your API credentials:
npx convex env set TWILIO_ACCOUNT_SID=ACxxxxx
npx convex env set TWILIO_AUTH_TOKEN=xxxxx
Instantiate a Twilio Component client in a file in your app's convex/
folder:
// convex/example.ts
import { Twilio } from "@convex-dev/twilio";
import { components } from "./_generated/api";
export const twilio = new Twilio(components.twilio, {
// optionally pass in the default "from" phone number you'll be using
// this must be a phone number you've created with Twilio
defaultFrom: process.env.TWILIO_PHONE_NUMBER!,
});
Register Twilio webhook handlers by creating an http.ts
file in your convex/
folder and use the client you've exported above:
// http.ts
import { twilio } from "./example";
import { httpRouter } from "convex/server";
const http = httpRouter();
// this call registers the routes necessary for the component
twilio.registerRoutes(http);
export default http;
Sending Messages
To send a message use the Convex action sendMessage
:
// convex/messages.ts
import { v } from "convex/values";
import { internalAction } from "./_generated/server";
export const sendSms = internalAction({
handler: async (ctx, args) => {
const status = await twilio.sendMessage(ctx, {
to: "+14158675309",
body: "Hey Jenny",
});
},
});
By querying the message (see below) you can check for the status (Twilio Statuses). The component subscribes to status updates and writes the most up-to-date status into the database.
Receiving Messages
To receive messages, you will associate a webhook handler provided by the component with the Twilio phone number you'd like to use.
twilio.registerRoutes
registers two webhook HTTP handlers in your your Convex app's deployment:
YOUR_CONVEX_SITE_URL/twilio/message-status
- capture and store delivery status of messages you send.YOUR_CONVEX_SITE_URL/twilio/incoming-message
- capture and store messages sent to your Twilio phone number.
Note: You may pass a custom httpPrefix
to Twilio
if you want to
route Twilio endpoints somewhere other than YOUR_CONVEX_SITE_URL/twilio/*
.
For instance, to route to YOUR_CONVEX_SITE_URL/custom-twilio/message-status
, set:
export const twilio = new Twilio(components.twilio, {
httpPrefix: "/custom-twilio",
});
You can associate it with your Twilio phone number in two ways:
Using the Twilio console in the "Configure" tab of the phone number, under "Messaging Configuration" -> "A messsage comes in" -> "URL".
By calling
registerIncomingSmsHandler
exposed by the component client, passing it the phone number's SID:
export const registerIncomingSmsHandler = internalAction({
args: {},
handler: async (ctx) => {
return await twilio.registerIncomingSmsHandler(ctx, {
sid: "YOUR_TWILIO_PHONE_NUMBER_SID",
});
},
});
Once it is configured, incoming messages will be captured by the component and logged in the messages
table.
You can execute your own logic upon receiving an incoming message, by providing a callback when instantiating the Twilio Component client:
// convex/example.ts
import { Twilio, messageValidator } from "@convex-dev/twilio";
const twilio = new Twilio(components.twilio);
twilio.incomingMessageCallback = internal.example.handleIncomingMessage;
export const handleIncomingMessage = internalMutation({
args: {
message: messageValidator,
},
handler: async (ctx, message) => {
// Use ctx here to update the database or schedule other actions.
// This is in the same transaction as the component's message insertion.
console.log("Incoming message", message);
},
});
If the handleIncomingMessage
callback throws an error, the message will not be
saved and the webhook will throw an error. Twilio
does not retry webhook requests,
but you can replay them manually from the Twilio "Error logs" console.
Querying Messages
To list all the mssages, use the list
method in your Convex function.
To list all the incoming or outgoing messages, use listIncoming
and listOutgoing
methods:
// convex/messages.ts
// ...
export const list = query({
args: {},
handler: async (ctx) => {
const allMessages = await twilio.list(ctx);
const receivedMessages = await twilio.listIncoming(ctx);
const sentMessages = await twilio.listOutgoing(ctx);
return { allMessages, receivedMessages, sentMessages };
},
});
To get a single message by its sid, use getMessageBySid
:
export const getMessageBySid = query({
args: {
sid: v.string(),
},
handler: async (ctx, args) => {
return await twilio.getMessageBySid(ctx, args);
},
});
Get messages by the "to" phone number:
export const getMessagesTo = query({
args: {
to: v.string(),
},
handler: async (ctx, args) => {
return await twilio.getMessagesTo(ctx, args);
},
});
Get messages by the "from" phone number:
export const getMessagesFrom = query({
args: {
from: v.string(),
},
handler: async (ctx, args) => {
return await twilio.getMessagesFrom(ctx, args);
},
});
You can also get all messages to and from a particular number:
export const getMessagesByCounterparty = query({
args: {
from: v.string(),
},
handler: async (ctx, args) => {
return await twilio.getMessagesByCounterparty(ctx, args);
},
});