---
title: "Setup Twilio Number"
method: POST
path: "/api/channels/twilio/setup"
tags: ["channels", "channels", "twilio-voice"]
---

# Setup Twilio Number

`POST /api/channels/twilio/setup`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/channels/twilio/setup`
- Auth: none declared

Configure a Twilio phone number for voice calls.

Two paths:
- Manual paste — body carries `twilio_account_sid` + `twilio_auth_token`,
  we INSERT a fresh `channel_account` row keyed by phone number.
- Connect resume — body carries `account_id` referring to the pending
  Connect row created in `/connect/callback`. We resolve creds via
  `get_twilio_creds()` (platform token, server-side), then MUTATE the
  pending row in place: `external_id` AC-SID → +E.164 phone, status
  `pending` → `active`. Avoids leaving an orphan AC-SID-keyed row.

## Request body

- TwilioSetupRequest: Request body for configuring a Twilio phone number. Two auth modes: - Manual paste: caller passes `twilio_account_sid` + `twilio_auth_token`. - Connect resume: caller passes `account_id` referring to a pending Connect row whose creds we resolve server-side via `get_twilio_creds()`. Exactly one shape must be provided — enforced in the endpoint.
  - `phone_number` string, required: Phone number in E.164 format (e.g., +15551234567)
  - `twilio_account_sid` string, nullable
  - `twilio_auth_token` string, nullable
  - `account_id` integer, nullable: Pending Connect row id — when set, creds are resolved server-side.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/d84e7dc9977d?raw)