---
name: bijection-twilio
description: "Evaluate and integrate the Twilio component with Bijection."
---

# Twilio

SMS sending and receiving

- Package: @bijectionhq/twilio
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/twilio/tree/0308857a45349e59d3be429350720779acbabc88
- Upstream: https://github.com/convex/twilio/tree/54df32e8c37aeb9692f19efa3b8c3e2cb3719e00
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/twilio

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/twilio.git
cd twilio
git checkout 0308857a45349e59d3be429350720779acbabc88
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/twilio. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Twilio SMS. Follow the installation and configuration steps exactly.

# Twilio SMS

## Instructions

This Twilio component integrates SMS messaging capabilities into your Convex app. It handles both sending outgoing messages through Twilio's API and receiving incoming messages via webhook handlers. The component automatically stores message status updates and provides query functions to retrieve message history, enabling you to build SMS-driven features without managing webhook infrastructure or message persistence.

### Installation

```bash
npm install @convex-dev/twilio
```

Current npm version: `@convex-dev/twilio@0.2.2`

## Use cases

- Build notification systems that send SMS alerts for order updates, appointment reminders, or security events
- Create two-way SMS customer support where users can text your business number and agents can respond
- Implement SMS-based authentication flows with verification codes sent through Twilio
- Build SMS marketing campaigns that track delivery status and handle opt-out responses
- Create SMS chatbots that process incoming messages and respond based on business logic

## How it works

The component requires Twilio API credentials and registers HTTP webhook routes (`/twilio/message-status` and `/twilio/incoming-message`) in your Convex app. You instantiate a Twilio client in your functions and call `sendMessage()` from actions to send SMS messages.

For incoming messages, you associate your Twilio phone number with the webhook URL either through the Twilio console or by calling `registerIncomingSmsHandler()`. The component automatically stores all messages in a database table and provides query methods like `list()`, `getMessageBySid()`, and `getMessagesByCounterparty()`.

You can execute custom logic on incoming messages by setting an `incomingMessageCallback` that runs in the same transaction as message storage. The component tracks message delivery status updates from Twilio, so you can monitor whether SMS messages were successfully delivered.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Twilio SMS is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Ftwilio)
- [GitHub repository](https://github.com/get-convex/twilio)
- [Convex Components Directory](https://www.convex.dev/components/twilio)
- [Convex documentation](https://docs.convex.dev)