Twilio Proxy API is a communication platform that enables businesses to build secure and scalable customer interactions. With this API, companies can create virtual phone numbers and manage communication between customers and agents without revealing personal contact information. Twilio Proxy API facilitates seamless text messaging and voice calls, while also providing features such as message history and analytics to track interactions.
components:
schemas:
proxy.v1.service.session.interaction:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KI[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Interaction
resource.
session_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the parent
[Session](https://www.twilio.com/docs/proxy/api/session) resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the parent
[Service](https://www.twilio.com/docs/proxy/api/service) resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Interaction resource.
data:
type: string
nullable: true
description: >-
A JSON string that includes the message body of message interactions
(e.g. `{"body": "hello"}`) or the call duration (when available) of
a call (e.g. `{"duration": "5"}`).
x-twilio:
pii:
handling: sensitive
deleteSla: 30
type:
type: string
$ref: '#/components/schemas/interaction_enum_type'
nullable: true
description: >-
The Type of the Interaction. Can be: `message`, `voice` or
`unknown`.
inbound_participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the inbound
[Participant](https://www.twilio.com/docs/proxy/api/participant)
resource.
inbound_resource_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the inbound resource; either the
[Call](https://www.twilio.com/docs/voice/api/call-resource) or
[Message](https://www.twilio.com/docs/sms/api/message-resource).
inbound_resource_status:
type: string
$ref: '#/components/schemas/interaction_enum_resource_status'
nullable: true
description: >-
The inbound resource status of the Interaction. Will always be
`delivered` for messages and `in-progress` for calls.
inbound_resource_type:
type: string
nullable: true
description: >-
The inbound resource type. Can be
[Call](https://www.twilio.com/docs/voice/api/call-resource) or
[Message](https://www.twilio.com/docs/sms/api/message-resource).
inbound_resource_url:
type: string
format: uri
nullable: true
description: The URL of the Twilio inbound resource
outbound_participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the outbound
[Participant](https://www.twilio.com/docs/proxy/api/participant)).
outbound_resource_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the outbound resource; either the
[Call](https://www.twilio.com/docs/voice/api/call-resource) or
[Message](https://www.twilio.com/docs/sms/api/message-resource).
outbound_resource_status:
type: string
$ref: '#/components/schemas/interaction_enum_resource_status'
nullable: true
description: >-
The outbound resource status of the Interaction. Can be: `accepted`,
`canceled`, `deleted`, `delivered`, `delivery-unknown`, `failed`,
`partially-delivered`, `queued`, `read`, `received`, `receiving`,
`scheduled`, `sending`, `sent`, `undelivered`, or `unknown` for
messages. Can be `initiated` or `completed` or `unknown` for calls.
outbound_resource_type:
type: string
nullable: true
description: >-
The outbound resource type. Can be:
[Call](https://www.twilio.com/docs/voice/api/call-resource) or
[Message](https://www.twilio.com/docs/sms/api/message-resource).
outbound_resource_url:
type: string
format: uri
nullable: true
description: The URL of the Twilio outbound resource.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the Interaction was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Interaction resource.
interaction_enum_type:
type: string
enum:
- message
- voice
- unknown
interaction_enum_resource_status:
type: string
enum:
- accepted
- answered
- busy
- canceled
- completed
- deleted
- delivered
- delivery-unknown
- failed
- in-progress
- initiated
- no-answer
- queued
- received
- receiving
- ringing
- scheduled
- sending
- sent
- undelivered
- unknown
proxy.v1.service.session.participant.message_interaction:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KI[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the MessageInteraction
resource.
session_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the parent
[Session](https://www.twilio.com/docs/proxy/api/session) resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the parent
[Service](https://www.twilio.com/docs/proxy/api/service) resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the MessageInteraction resource.
data:
type: string
nullable: true
description: >-
A JSON string that includes the message body sent to the
participant. (e.g. `{"body": "hello"}`)
x-twilio:
pii:
handling: sensitive
deleteSla: 30
type:
type: string
$ref: '#/components/schemas/message_interaction_enum_type'
nullable: true
description: The Type of Message Interaction. This value is always `message`.
participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Participant](https://www.twilio.com/docs/proxy/api/participant)
resource.
inbound_participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: Always empty for created Message Interactions.
inbound_resource_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: Always empty for created Message Interactions.
inbound_resource_status:
type: string
$ref: '#/components/schemas/message_interaction_enum_resource_status'
nullable: true
description: Always empty for created Message Interactions.
inbound_resource_type:
type: string
nullable: true
description: Always empty for created Message Interactions.
inbound_resource_url:
type: string
format: uri
nullable: true
description: Always empty for created Message Interactions.
outbound_participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the outbound
[Participant](https://www.twilio.com/docs/proxy/api/participant)
resource.
outbound_resource_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the outbound
[Message](https://www.twilio.com/docs/sms/api/message-resource)
resource.
outbound_resource_status:
type: string
$ref: '#/components/schemas/message_interaction_enum_resource_status'
nullable: true
description: >-
The outbound message resource status. Can be: `accepted`, `deleted`,
`delivered`, `delivery-unknown`, `failed`, `queued`, `received`,
`receiving`, `scheduled`, `sending`, `sent`, `undelivered`, or
`unknown`.
outbound_resource_type:
type: string
nullable: true
description: The outbound resource type. This value is always `Message`.
outbound_resource_url:
type: string
format: uri
nullable: true
description: The URL of the Twilio message resource.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the MessageInteraction resource.
message_interaction_enum_type:
type: string
enum:
- message
- voice
- unknown
message_interaction_enum_resource_status:
type: string
enum:
- accepted
- answered
- busy
- canceled
- completed
- deleted
- delivered
- delivery-unknown
- failed
- in-progress
- initiated
- no-answer
- queued
- received
- receiving
- ringing
- scheduled
- sending
- sent
- undelivered
- unknown
proxy.v1.service.session.participant:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KP[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Participant
resource.
session_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the parent
[Session](https://www.twilio.com/docs/proxy/api/session) resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the resource's parent
[Service](https://www.twilio.com/docs/proxy/api/service) resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Participant resource.
friendly_name:
type: string
nullable: true
description: >-
The string that you assigned to describe the participant. This value
must be 255 characters or fewer. Supports UTF-8 characters. **This
value should not have PII.**
identifier:
type: string
nullable: true
description: >-
The phone number or channel identifier of the Participant. This
value must be 191 characters or fewer. Supports UTF-8 characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
proxy_identifier:
type: string
nullable: true
description: >-
The phone number or short code (masked number) of the participant's
partner. The participant will call or message the partner
participant at this number.
proxy_identifier_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^PN[0-9a-fA-F]{32}$
nullable: true
description: The SID of the Proxy Identifier assigned to the Participant.
date_deleted:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the
Participant was removed from the session.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Participant resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs to resources related the participant.
proxy.v1.service.phone_number:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^PN[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the PhoneNumber
resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the PhoneNumber resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the PhoneNumber resource's parent
[Service](https://www.twilio.com/docs/proxy/api/service) resource.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
phone_number:
type: string
format: phone-number
nullable: true
description: >-
The phone number in
[E.164](https://www.twilio.com/docs/glossary/what-e164) format,
which consists of a + followed by the country code and subscriber
number.
friendly_name:
type: string
nullable: true
description: The string that you assigned to describe the resource.
iso_country:
type: string
nullable: true
description: The ISO Country Code for the phone number.
capabilities:
type: object
format: phone-number-capabilities
properties:
mms:
type: boolean
sms:
type: boolean
voice:
type: boolean
fax:
type: boolean
nullable: true
description: The capabilities of the phone number.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the PhoneNumber resource.
is_reserved:
type: boolean
nullable: true
description: >-
Whether the phone number should be reserved and not be assigned to a
participant using proxy pool logic. See [Reserved Phone
Numbers](https://www.twilio.com/docs/proxy/reserved-phone-numbers)
for more information.
in_use:
type: integer
nullable: true
description: >-
The number of open session assigned to the number. See the [How many
Phone Numbers do I
need?](https://www.twilio.com/docs/proxy/phone-numbers-needed) guide
for more information.
proxy.v1.service:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Service resource.
unique_name:
type: string
nullable: true
description: >-
An application-defined string that uniquely identifies the resource.
This value must be 191 characters or fewer in length and be unique.
Supports UTF-8 characters. **This value should not have PII.**
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Service resource.
chat_instance_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the Chat Service Instance managed by Proxy Service. The
Chat Service enables Proxy to forward SMS and channel messages to
this chat instance. This is a one-to-one relationship.
callback_url:
type: string
format: uri
nullable: true
description: The URL we call when the interaction status changes.
default_ttl:
type: integer
nullable: true
description: >-
The default `ttl` value for Sessions created in the Service. The TTL
(time to live) is measured in seconds after the Session's last
create or last Interaction. The default value of `0` indicates an
unlimited Session length. You can override a Session's default TTL
value by setting its `ttl` value.
number_selection_behavior:
type: string
$ref: '#/components/schemas/service_enum_number_selection_behavior'
nullable: true
description: >-
The preference for Proxy Number selection in the Service instance.
Can be: `prefer-sticky` or `avoid-sticky`. `prefer-sticky` means
that we will try and select the same Proxy Number for a given
participant if they have previous
[Sessions](https://www.twilio.com/docs/proxy/api/session), but we
will not fail if that Proxy Number cannot be used. `avoid-sticky`
means that we will try to use different Proxy Numbers as long as
that is possible within a given pool rather than try and use a
previously assigned number.
geo_match_level:
type: string
$ref: '#/components/schemas/service_enum_geo_match_level'
nullable: true
description: >-
Where a proxy number must be located relative to the participant
identifier. Can be: `country`, `area-code`, or `extended-area-code`.
The default value is `country` and more specific areas than
`country` are only available in North America.
intercept_callback_url:
type: string
format: uri
nullable: true
description: >-
The URL we call on each interaction. If we receive a 403 status, we
block the interaction; otherwise the interaction continues.
out_of_session_callback_url:
type: string
format: uri
nullable: true
description: >-
The URL we call when an inbound call or SMS action occurs on a
closed or non-existent Session. If your server (or a Twilio
[function](https://www.twilio.com/en-us/serverless/functions))
responds with valid
[TwiML](https://www.twilio.com/docs/voice/twiml), we will process
it. This means it is possible, for example, to play a message for a
call, send an automated text message response, or redirect a call to
another Phone Number. See [Out-of-Session Callback Response
Guide](https://www.twilio.com/docs/proxy/out-session-callback-response-guide)
for more information.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Service resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs of resources related to the Service.
service_enum_geo_match_level:
type: string
enum:
- area-code
- overlay
- radius
- country
service_enum_number_selection_behavior:
type: string
enum:
- avoid-sticky
- prefer-sticky
proxy.v1.service.session:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KC[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Session resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/proxy/api/service) the session
is associated with.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Session resource.
date_started:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the
Session started.
date_ended:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the
Session ended.
date_last_interaction:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the
Session last had an interaction.
date_expiry:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the
Session should expire. If this is value is present, it overrides the
`ttl` value.
unique_name:
type: string
nullable: true
description: >-
An application-defined string that uniquely identifies the resource.
This value must be 191 characters or fewer in length and be unique.
Supports UTF-8 characters. **This value should not have PII.**
status:
type: string
$ref: '#/components/schemas/session_enum_status'
nullable: true
description: >-
The status of the Session. Can be: `open`, `in-progress`, `closed`,
`failed`, or `unknown`.
closed_reason:
type: string
nullable: true
description: The reason the Session ended.
ttl:
type: integer
nullable: true
description: >-
The time, in seconds, when the session will expire. The time is
measured from the last Session create or the Session's last
Interaction.
mode:
type: string
$ref: '#/components/schemas/session_enum_mode'
nullable: true
description: >-
The Mode of the Session. Can be: `message-only`, `voice-only`, or
`voice-and-message`.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Session resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs of resources related to the Session.
session_enum_status:
type: string
enum:
- open
- in-progress
- closed
- failed
- unknown
session_enum_mode:
type: string
enum:
- message-only
- voice-only
- voice-and-message
proxy.v1.service.short_code:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^SC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the ShortCode
resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the ShortCode resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^KS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the ShortCode resource's parent
[Service](https://www.twilio.com/docs/proxy/api/service) resource.
date_created:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time
in GMT when the resource was last updated.
short_code:
type: string
nullable: true
description: The short code's number.
iso_country:
type: string
nullable: true
description: The ISO Country Code for the short code.
capabilities:
type: object
format: phone-number-capabilities
properties:
mms:
type: boolean
sms:
type: boolean
voice:
type: boolean
fax:
type: boolean
nullable: true
description: The capabilities of the short code.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the ShortCode resource.
is_reserved:
type: boolean
nullable: true
description: >-
Whether the short code should be reserved and not be assigned to a
participant using proxy pool logic. See [Reserved Phone
Numbers](https://www.twilio.com/docs/proxy/reserved-phone-numbers)
for more information.
ListInteractionResponse:
type: object
properties:
interactions:
type: array
items:
$ref: '#/components/schemas/proxy.v1.service.session.interaction'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
CreateMessageInteractionRequest:
type: object
properties:
Body:
type: string
description: The message to send to the participant
MediaUrl:
type: array
items:
type: string
format: uri
description: Reserved. Not currently supported.
ListMessageInteractionResponse:
type: object
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/proxy-openapi-original.yml