openapi: 3.0.0 info: title: Vapi Phone Numbers API description: Vapi API — Phone Numbers resource. Voice AI for developers. version: '1.0' contact: name: Vapi url: https://vapi.ai servers: - url: https://api.vapi.ai security: - bearer: [] tags: - name: Phone Numbers description: Phone Numbers endpoints. paths: /phone-number: post: operationId: PhoneNumberController_create summary: Create Phone Number parameters: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateByoPhoneNumberDTO' title: ByoPhoneNumber - $ref: '#/components/schemas/CreateTwilioPhoneNumberDTO' title: TwilioPhoneNumber - $ref: '#/components/schemas/CreateVonagePhoneNumberDTO' title: VonagePhoneNumber - $ref: '#/components/schemas/CreateVapiPhoneNumberDTO' title: VapiPhoneNumber - $ref: '#/components/schemas/CreateTelnyxPhoneNumberDTO' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/CreateByoPhoneNumberDTO' twilio: '#/components/schemas/CreateTwilioPhoneNumberDTO' vonage: '#/components/schemas/CreateVonagePhoneNumberDTO' vapi: '#/components/schemas/CreateVapiPhoneNumberDTO' telnyx: '#/components/schemas/CreateTelnyxPhoneNumberDTO' responses: '201': description: '' content: application/json: schema: title: PhoneNumber oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' title: ByoPhoneNumber - $ref: '#/components/schemas/TwilioPhoneNumber' title: TwilioPhoneNumber - $ref: '#/components/schemas/VonagePhoneNumber' title: VonagePhoneNumber - $ref: '#/components/schemas/VapiPhoneNumber' title: VapiPhoneNumber - $ref: '#/components/schemas/TelnyxPhoneNumber' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/ByoPhoneNumber' twilio: '#/components/schemas/TwilioPhoneNumber' vonage: '#/components/schemas/VonagePhoneNumber' vapi: '#/components/schemas/VapiPhoneNumber' telnyx: '#/components/schemas/TelnyxPhoneNumber' tags: - Phone Numbers security: - bearer: [] get: operationId: PhoneNumberController_findAll summary: List Phone Numbers parameters: - name: limit required: false in: query description: This is the maximum number of items to return. Defaults to 100. schema: minimum: 0 maximum: 1000 type: number - name: createdAtGt required: false in: query description: This will return items where the createdAt is greater than the specified value. schema: format: date-time type: string - name: createdAtLt required: false in: query description: This will return items where the createdAt is less than the specified value. schema: format: date-time type: string - name: createdAtGe required: false in: query description: This will return items where the createdAt is greater than or equal to the specified value. schema: format: date-time type: string - name: createdAtLe required: false in: query description: This will return items where the createdAt is less than or equal to the specified value. schema: format: date-time type: string - name: updatedAtGt required: false in: query description: This will return items where the updatedAt is greater than the specified value. schema: format: date-time type: string - name: updatedAtLt required: false in: query description: This will return items where the updatedAt is less than the specified value. schema: format: date-time type: string - name: updatedAtGe required: false in: query description: This will return items where the updatedAt is greater than or equal to the specified value. schema: format: date-time type: string - name: updatedAtLe required: false in: query description: This will return items where the updatedAt is less than or equal to the specified value. schema: format: date-time type: string responses: '200': description: '' content: application/json: schema: type: array items: title: PhoneNumber oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' title: ByoPhoneNumber - $ref: '#/components/schemas/TwilioPhoneNumber' title: TwilioPhoneNumber - $ref: '#/components/schemas/VonagePhoneNumber' title: VonagePhoneNumber - $ref: '#/components/schemas/VapiPhoneNumber' title: VapiPhoneNumber - $ref: '#/components/schemas/TelnyxPhoneNumber' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/ByoPhoneNumber' twilio: '#/components/schemas/TwilioPhoneNumber' vonage: '#/components/schemas/VonagePhoneNumber' vapi: '#/components/schemas/VapiPhoneNumber' telnyx: '#/components/schemas/TelnyxPhoneNumber' tags: - Phone Numbers security: - bearer: [] /v2/phone-number: get: operationId: PhoneNumberController_findAllPaginated summary: List Phone Numbers parameters: - name: search required: false in: query description: This will search phone numbers by name, number, or SIP URI (partial match, case-insensitive). schema: maxLength: 100 type: string - name: page required: false in: query description: This is the page number to return. Defaults to 1. schema: minimum: 1 type: number - name: sortOrder required: false in: query description: This is the sort order for pagination. Defaults to 'DESC'. schema: enum: - ASC - DESC type: string - name: sortBy required: false in: query description: This is the column to sort by. Defaults to 'createdAt'. schema: enum: - createdAt - duration - cost type: string - name: limit required: false in: query description: This is the maximum number of items to return. Defaults to 100. schema: minimum: 0 maximum: 1000 type: number - name: createdAtGt required: false in: query description: This will return items where the createdAt is greater than the specified value. schema: format: date-time type: string - name: createdAtLt required: false in: query description: This will return items where the createdAt is less than the specified value. schema: format: date-time type: string - name: createdAtGe required: false in: query description: This will return items where the createdAt is greater than or equal to the specified value. schema: format: date-time type: string - name: createdAtLe required: false in: query description: This will return items where the createdAt is less than or equal to the specified value. schema: format: date-time type: string - name: updatedAtGt required: false in: query description: This will return items where the updatedAt is greater than the specified value. schema: format: date-time type: string - name: updatedAtLt required: false in: query description: This will return items where the updatedAt is less than the specified value. schema: format: date-time type: string - name: updatedAtGe required: false in: query description: This will return items where the updatedAt is greater than or equal to the specified value. schema: format: date-time type: string - name: updatedAtLe required: false in: query description: This will return items where the updatedAt is less than or equal to the specified value. schema: format: date-time type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PhoneNumberPaginatedResponse' tags: - Phone Numbers security: - bearer: [] /phone-number/{id}: get: operationId: PhoneNumberController_findOne summary: Get Phone Number parameters: - name: id required: true in: path description: The unique identifier for the resource. schema: format: uuid type: string responses: '200': description: '' content: application/json: schema: title: PhoneNumber oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' title: ByoPhoneNumber - $ref: '#/components/schemas/TwilioPhoneNumber' title: TwilioPhoneNumber - $ref: '#/components/schemas/VonagePhoneNumber' title: VonagePhoneNumber - $ref: '#/components/schemas/VapiPhoneNumber' title: VapiPhoneNumber - $ref: '#/components/schemas/TelnyxPhoneNumber' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/ByoPhoneNumber' twilio: '#/components/schemas/TwilioPhoneNumber' vonage: '#/components/schemas/VonagePhoneNumber' vapi: '#/components/schemas/VapiPhoneNumber' telnyx: '#/components/schemas/TelnyxPhoneNumber' tags: - Phone Numbers security: - bearer: [] patch: operationId: PhoneNumberController_update summary: Update Phone Number parameters: - name: id required: true in: path description: The unique identifier for the resource. schema: format: uuid type: string requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/UpdateByoPhoneNumberDTO' title: ByoPhoneNumber - $ref: '#/components/schemas/UpdateTwilioPhoneNumberDTO' title: TwilioPhoneNumber - $ref: '#/components/schemas/UpdateVonagePhoneNumberDTO' title: VonagePhoneNumber - $ref: '#/components/schemas/UpdateVapiPhoneNumberDTO' title: VapiPhoneNumber - $ref: '#/components/schemas/UpdateTelnyxPhoneNumberDTO' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/UpdateByoPhoneNumberDTO' twilio: '#/components/schemas/UpdateTwilioPhoneNumberDTO' vonage: '#/components/schemas/UpdateVonagePhoneNumberDTO' vapi: '#/components/schemas/UpdateVapiPhoneNumberDTO' telnyx: '#/components/schemas/UpdateTelnyxPhoneNumberDTO' responses: '200': description: '' content: application/json: schema: title: PhoneNumber oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' title: ByoPhoneNumber - $ref: '#/components/schemas/TwilioPhoneNumber' title: TwilioPhoneNumber - $ref: '#/components/schemas/VonagePhoneNumber' title: VonagePhoneNumber - $ref: '#/components/schemas/VapiPhoneNumber' title: VapiPhoneNumber - $ref: '#/components/schemas/TelnyxPhoneNumber' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/ByoPhoneNumber' twilio: '#/components/schemas/TwilioPhoneNumber' vonage: '#/components/schemas/VonagePhoneNumber' vapi: '#/components/schemas/VapiPhoneNumber' telnyx: '#/components/schemas/TelnyxPhoneNumber' tags: - Phone Numbers security: - bearer: [] delete: operationId: PhoneNumberController_remove summary: Delete Phone Number parameters: - name: id required: true in: path description: The unique identifier for the resource. schema: format: uuid type: string responses: '200': description: '' content: application/json: schema: title: PhoneNumber oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' title: ByoPhoneNumber - $ref: '#/components/schemas/TwilioPhoneNumber' title: TwilioPhoneNumber - $ref: '#/components/schemas/VonagePhoneNumber' title: VonagePhoneNumber - $ref: '#/components/schemas/VapiPhoneNumber' title: VapiPhoneNumber - $ref: '#/components/schemas/TelnyxPhoneNumber' title: TelnyxPhoneNumber discriminator: propertyName: provider mapping: byo-phone-number: '#/components/schemas/ByoPhoneNumber' twilio: '#/components/schemas/TwilioPhoneNumber' vonage: '#/components/schemas/VonagePhoneNumber' vapi: '#/components/schemas/VapiPhoneNumber' telnyx: '#/components/schemas/TelnyxPhoneNumber' tags: - Phone Numbers security: - bearer: [] components: securitySchemes: bearer: scheme: bearer bearerFormat: Bearer type: http description: Retrieve your API Key from [Dashboard](dashboard.vapi.ai). schemas: BackoffPlan: type: object properties: type: type: object description: 'This is the type of backoff plan to use. Defaults to fixed. @default fixed' enum: - fixed - exponential example: fixed maxRetries: type: number description: 'This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0' minimum: 0 maximum: 10 example: 0 baseDelaySeconds: type: number description: This is the base delay in seconds. For linear backoff, this is the delay between each retry. For exponential backoff, this is the initial delay. minimum: 0 maximum: 10 example: 1 excludedStatusCodes: description: 'This is the excluded status codes. If the response status code is in this list, the request will not be retried. By default, the request will be retried for any non-2xx status code.' example: - 400 - 401 - 403 - 404 type: array items: type: object required: - type - maxRetries - baseDelaySeconds ByoPhoneNumber: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to bring your own phone numbers from your own SIP trunks or Carriers. enum: - byo-phone-number numberE164CheckEnabled: type: boolean description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which should be used if you know your use case requires it. Use cases: - `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to non-E164 numbers on your SIP trunks. - `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls. If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`). @default true (E164 check is enabled)' default: true id: type: string description: This is the unique identifier for the phone number. orgId: type: string description: This is the unique identifier for the org that this phone number belongs to. createdAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was created. updatedAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was last updated. status: type: string description: This is the status of the phone number. enum: - active - activating - blocked name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: This is the number of the customer. minLength: 3 maxLength: 40 credentialId: type: string description: 'This is the credential of your own SIP trunk or Carrier (type `byo-sip-trunk`) which can be used to make calls to this phone number. You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.' required: - provider - id - orgId - createdAt - updatedAt - credentialId ContextEngineeringPlanAll: type: object properties: type: type: string enum: - all required: - type ContextEngineeringPlanLastNMessages: type: object properties: type: type: string enum: - lastNMessages maxMessages: type: number description: This is the maximum number of messages to include in the context engineering plan. minimum: 0 required: - type - maxMessages ContextEngineeringPlanNone: type: object properties: type: type: string enum: - none required: - type CreateByoPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to bring your own phone numbers from your own SIP trunks or Carriers. enum: - byo-phone-number numberE164CheckEnabled: type: boolean description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which should be used if you know your use case requires it. Use cases: - `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to non-E164 numbers on your SIP trunks. - `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls. If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`). @default true (E164 check is enabled)' default: true number: type: string description: This is the number of the customer. minLength: 3 maxLength: 40 credentialId: type: string description: 'This is the credential of your own SIP trunk or Carrier (type `byo-sip-trunk`) which can be used to make calls to this phone number. You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.' name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' required: - provider - credentialId CreateTelnyxPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Telnyx. enum: - telnyx number: type: string description: These are the digits of the phone number you own on your Telnyx. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' required: - provider - number - credentialId CreateTwilioPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Twilio. enum: - twilio smsEnabled: type: boolean description: 'Controls whether Vapi sets the messaging webhook URL on the Twilio number during import. If set to `false`, Vapi will not update the Twilio messaging URL, leaving it as is. If `true` or omitted (default), Vapi will configure both the voice and messaging URLs. @default true' default: true number: type: string description: These are the digits of the phone number you own on your Twilio. twilioAccountSid: type: string description: This is the Twilio Account SID for the phone number. twilioAuthToken: type: string description: This is the Twilio Auth Token for the phone number. twilioApiKey: type: string description: This is the Twilio API Key for the phone number. twilioApiSecret: type: string description: This is the Twilio API Secret for the phone number. name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' required: - provider - number - twilioAccountSid CreateVapiPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to create free SIP phone numbers on Vapi. enum: - vapi numberDesiredAreaCode: type: string description: This is the area code of the phone number to purchase. minLength: 3 maxLength: 3 sipUri: type: string description: 'This is the SIP URI of the phone number. You can SIP INVITE this. The assistant attached to this number will answer. This is case-insensitive.' authentication: description: 'This enables authentication for incoming SIP INVITE requests to the `sipUri`. If not set, any username/password to the 401 challenge of the SIP INVITE will be accepted.' allOf: - $ref: '#/components/schemas/SipAuthentication' name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' required: - provider CreateVonagePhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Vonage. enum: - vonage number: type: string description: These are the digits of the phone number you own on your Vonage. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' required: - provider - number - credentialId CustomMessage: type: object properties: contents: type: array description: 'This is an alternative to the `content` property. It allows to specify variants of the same content, one per language. Usage: - If your assistants are multilingual, you can provide content for each language. - If you don''t provide content for a language, the first item in the array will be automatically translated to the active language at that moment. This will override the `content` property.' items: oneOf: - $ref: '#/components/schemas/TextContent' title: Text type: type: string description: This is a custom message. enum: - custom-message content: type: string description: This is the content that the assistant will say when this message is triggered. maxLength: 1000 required: - type PaginationMeta: type: object properties: itemsPerPage: type: number totalItems: type: number currentPage: type: number totalPages: type: number hasNextPage: type: boolean sortOrder: type: string enum: - ASC - DESC itemsBeyondRetention: type: boolean createdAtLe: format: date-time type: string createdAtGe: format: date-time type: string required: - itemsPerPage - totalItems - currentPage PhoneNumberCallEndingHookFilter: type: object properties: type: type: string description: This is the type of filter - currently only "oneOf" is supported enum: - oneOf maxLength: 1000 key: type: string description: This is the key to filter on - only "call.endedReason" is allowed for phone number call ending hooks enum: - call.endedReason maxLength: 1000 oneOf: type: array description: This is the array of assistant-request related ended reasons to match against enum: - assistant-request-failed - assistant-request-returned-error - assistant-request-returned-unspeakable-error - assistant-request-returned-invalid-assistant - assistant-request-returned-no-assistant - assistant-request-returned-forwarding-phone-number items: type: string enum: - assistant-request-failed - assistant-request-returned-error - assistant-request-returned-unspeakable-error - assistant-request-returned-invalid-assistant - assistant-request-returned-no-assistant - assistant-request-returned-forwarding-phone-number required: - type - key - oneOf PhoneNumberCallRingingHookFilter: type: object properties: type: type: string description: This is the type of filter - matches when the specified field starts with any of the given prefixes enum: - startsWith maxLength: 1000 key: type: string description: The field to check. Currently only "number" (the caller's phone number) is supported. enum: - number maxLength: 1000 startsWith: type: array description: Array of prefixes to match. Do not include the + prefix. Inbound calls from numbers starting with any of these prefixes will trigger the hook actions. maxLength: 20 items: type: string maxLength: 20 example: - '91' - '86' - '7' required: - type - key - startsWith PhoneNumberHookCallEnding: type: object properties: 'on': type: string description: This is the event to trigger the hook on enum: - call.ending maxLength: 1000 filters: type: array description: Optional filters to decide when to trigger - restricted to assistant-request related ended reasons items: $ref: '#/components/schemas/PhoneNumberCallEndingHookFilter' do: description: This is the action to perform when the hook triggers oneOf: - $ref: '#/components/schemas/TransferPhoneNumberHookAction' title: TransferPhoneNumberHookAction - $ref: '#/components/schemas/SayPhoneNumberHookAction' title: SayPhoneNumberHookAction required: - 'on' PhoneNumberHookCallRinging: type: object properties: 'on': type: string description: This is the event to trigger the hook on enum: - call.ringing maxLength: 1000 filters: type: array description: Optional filters to decide when to trigger the hook. Currently supports filtering by caller country code. items: $ref: '#/components/schemas/PhoneNumberCallRingingHookFilter' do: type: array description: Only the first action will be executed. Additional actions will be ignored. items: oneOf: - $ref: '#/components/schemas/TransferPhoneNumberHookAction' title: TransferPhoneNumberHookAction - $ref: '#/components/schemas/SayPhoneNumberHookAction' title: SayPhoneNumberHookAction required: - 'on' - do PhoneNumberPaginatedResponse: type: object properties: results: type: array description: A list of phone numbers, which can be of any provider type. items: oneOf: - $ref: '#/components/schemas/ByoPhoneNumber' - $ref: '#/components/schemas/TwilioPhoneNumber' - $ref: '#/components/schemas/VonagePhoneNumber' - $ref: '#/components/schemas/VapiPhoneNumber' - $ref: '#/components/schemas/TelnyxPhoneNumber' metadata: description: Metadata about the pagination. allOf: - $ref: '#/components/schemas/PaginationMeta' required: - results - metadata SayPhoneNumberHookAction: type: object properties: type: type: string description: This is the type of action - must be "say" enum: - say exact: type: string description: This is the message to say maxLength: 4000 required: - type - exact Server: type: object properties: timeoutSeconds: type: number description: 'This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20' minimum: 1 maximum: 300 example: 20 credentialId: type: string description: The credential ID for server authentication example: 550e8400-e29b-41d4-a716-446655440000 staticIpAddressesEnabled: type: boolean description: 'If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false' example: false encryptedPaths: type: array description: This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. items: type: string url: type: string description: This is where the request will be sent. headers: type: object description: 'These are the headers to include in the request. Each key-value pair represents a header name and its value. Note: Specifying an Authorization header here will override the authorization provided by the `credentialId` (if provided). This is an anti-pattern and should be avoided outside of edge case scenarios.' backoffPlan: description: 'This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried). @default undefined (the request will not be retried)' allOf: - $ref: '#/components/schemas/BackoffPlan' SipAuthentication: type: object properties: realm: type: string description: This will be expected in the `realm` field of the `authorization` header of the SIP INVITE. Defaults to the SIP realm of the Vapi region serving the request (e.g. `sip.vapi.ai` for US, `sip.eu.vapi.ai` for EU). username: type: string description: This will be expected in the `username` field of the `authorization` header of the SIP INVITE. minLength: 20 maxLength: 40 password: type: string description: This will be expected to generate the `response` field of the `authorization` header of the SIP INVITE, through digest authentication. minLength: 20 maxLength: 40 required: - username - password SummaryPlan: type: object properties: messages: description: "These are the messages used to generate the summary.\n\n@default: ```\n[\n {\n \"role\": \"system\"\ ,\n \"content\": \"You are an expert note-taker. You will be given a transcript of a call. Summarize the call\ \ in 2-3 sentences. DO NOT return anything except the summary.\"\n },\n {\n \"role\": \"user\",\n \"content\"\ : \"Here is the transcript:\\n\\n{{transcript}}\\n\\n. Here is the ended reason of the call:\\n\\n{{endedReason}}\\\ n\\n\"\n }\n]```\n\nYou can customize by providing any messages you want.\n\nHere are the template variables\ \ available:\n- {{transcript}}: The transcript of the call from `call.artifact.transcript` \n- {{systemPrompt}}:\ \ The system prompt of the call from `assistant.model.messages[type=system].content` \n- {{messages}}: The messages\ \ of the call from `assistant.model.messages` \n- {{endedReason}}: The ended reason of the call from `call.endedReason`" type: array items: type: object enabled: type: boolean description: 'This determines whether a summary is generated and stored in `call.analysis.summary`. Defaults to true. Usage: - If you want to disable the summary, set this to false. @default true' timeoutSeconds: type: number description: 'This is how long the request is tried before giving up. When request times out, `call.analysis.summary` will be empty. Usage: - To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond. @default 5 seconds' minimum: 1 maximum: 60 TelnyxPhoneNumber: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Telnyx. enum: - telnyx id: type: string description: This is the unique identifier for the phone number. orgId: type: string description: This is the unique identifier for the org that this phone number belongs to. createdAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was created. updatedAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was last updated. status: type: string description: This is the status of the phone number. enum: - active - activating - blocked name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Telnyx. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. required: - provider - id - orgId - createdAt - updatedAt - number - credentialId TextContent: type: object properties: type: type: string enum: - text text: type: string language: type: string enum: - aa - ab - ae - af - ak - am - an - ar - as - av - ay - az - ba - be - bg - bh - bi - bm - bn - bo - br - bs - ca - ce - ch - co - cr - cs - cu - cv - cy - da - de - dv - dz - ee - el - en - eo - es - et - eu - fa - ff - fi - fj - fo - fr - fy - ga - gd - gl - gn - gu - gv - ha - he - hi - ho - hr - ht - hu - hy - hz - ia - id - ie - ig - ii - ik - io - is - it - iu - ja - jv - ka - kg - ki - kj - kk - kl - km - kn - ko - kr - ks - ku - kv - kw - ky - la - lb - lg - li - ln - lo - lt - lu - lv - mg - mh - mi - mk - ml - mn - mr - ms - mt - my - na - nb - nd - ne - ng - nl - nn - 'no' - nr - nv - ny - oc - oj - om - or - os - pa - pi - pl - ps - pt - qu - rm - rn - ro - ru - rw - sa - sc - sd - se - sg - si - sk - sl - sm - sn - so - sq - sr - ss - st - su - sv - sw - ta - te - tg - th - ti - tk - tl - tn - to - tr - ts - tt - tw - ty - ug - uk - ur - uz - ve - vi - vo - wa - wo - xh - yi - yue - yo - za - zh - zu required: - type - text - language TransferDestinationNumber: type: object properties: message: description: 'This is spoken to the customer before connecting them to the destination. Usage: - If this is not provided and transfer tool messages is not provided, default is "Transferring the call now". - If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set `assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message` for the destination assistant. This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the `contents` field.' oneOf: - type: string - $ref: '#/components/schemas/CustomMessage' type: type: string enum: - number numberE164CheckEnabled: type: boolean description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which should be used if you know your use case requires it. Use cases: - `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to non-E164 numbers on your SIP trunks. - `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls. If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`). @default true (E164 check is enabled)' default: true number: type: string description: This is the phone number to transfer the call to. minLength: 3 maxLength: 40 extension: type: string description: This is the extension to dial after transferring the call to the `number`. minLength: 1 maxLength: 10 callerId: type: string description: "This is the caller ID to use when transferring the call to the `number`.\n\nUsage:\n- If not provided,\ \ the caller ID will be the number the call is coming **from**.\n Example: a customer with number +14151111111\ \ calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller.\n\ \ For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number\ \ of the assistant.\n- To change this behavior, provide a `callerId`.\n- Set to '{{customer.number}}' to always\ \ use the customer's number as the caller ID.\n- Set to '{{phoneNumber.number}}' to always use the phone number\ \ of the assistant as the caller ID.\n- Set to any E164 number to always use that number as the caller ID. This\ \ needs to be a number that is owned or verified by your Transport provider like Twilio.\n\nFor Twilio, you can\ \ read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid" maxLength: 40 transferPlan: description: 'This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to `blind-transfer`. @default `transferPlan.mode=''blind-transfer''`' allOf: - $ref: '#/components/schemas/TransferPlan' description: type: string description: This is the description of the destination, used by the AI to choose when and how to transfer the call. required: - type - number TransferDestinationSip: type: object properties: message: description: 'This is spoken to the customer before connecting them to the destination. Usage: - If this is not provided and transfer tool messages is not provided, default is "Transferring the call now". - If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set `assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message` for the destination assistant. This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the `contents` field.' oneOf: - type: string - $ref: '#/components/schemas/CustomMessage' type: type: string enum: - sip sipUri: type: string description: This is the SIP URI to transfer the call to. callerId: type: string description: 'This is the caller ID to use when transferring the call to the `sipUri`. Usage: - If not provided, the caller ID will be determined by the SIP infrastructure. - Set to ''{{customer.number}}'' to always use the customer''s number as the caller ID. - Set to ''{{phoneNumber.number}}'' to always use the phone number of the assistant as the caller ID. - Set to any E164 number to always use that number as the caller ID. Only applicable when `transferPlan.sipVerb=''dial''`. Not applicable for SIP REFER.' maxLength: 40 transferPlan: description: 'This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to `blind-transfer`. @default `transferPlan.mode=''blind-transfer''`' allOf: - $ref: '#/components/schemas/TransferPlan' sipHeaders: type: object description: These are custom headers to be added to SIP refer during transfer call. description: type: string description: This is the description of the destination, used by the AI to choose when and how to transfer the call. required: - type - sipUri TransferFallbackPlan: type: object properties: message: description: This is the message the assistant will deliver to the customer if the transfer fails. oneOf: - type: string - $ref: '#/components/schemas/CustomMessage' endCallEnabled: type: boolean description: 'This controls what happens after delivering the failure message to the customer. - true: End the call after delivering the failure message (default) - false: Keep the assistant on the call to continue handling the customer''s request @default true' default: true required: - message TransferPhoneNumberHookAction: type: object properties: type: type: string description: This is the type of action - must be "transfer" enum: - transfer destination: description: This is the destination details for the transfer - can be a phone number or SIP URI oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination required: - type TransferPlan: type: object properties: mode: type: string description: 'This configures how transfer is executed and the experience of the destination party receiving the call. Usage: - `blind-transfer`: The assistant forwards the call to the destination without any message or summary. - `blind-transfer-add-summary-to-sip-header`: The assistant forwards the call to the destination and adds a SIP header X-Transfer-Summary to the call to include the summary. - `warm-transfer-say-message`: The assistant dials the destination, delivers the `message` to the destination party, connects the customer, and leaves the call. - `warm-transfer-say-summary`: The assistant dials the destination, provides a summary of the call to the destination party, connects the customer, and leaves the call. - `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`: The assistant dials the destination, waits for the operator to speak, delivers the `message` to the destination party, and then connects the customer. - `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`: The assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer. - `warm-transfer-twiml`: The assistant dials the destination, executes the twiml instructions on the destination call leg, connects the customer, and leaves the call. - `warm-transfer-experimental`: The assistant puts the customer on hold, dials the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the `fallbackMessage` to the customer and optionally ends the call. @default ''blind-transfer''' enum: - blind-transfer - blind-transfer-add-summary-to-sip-header - warm-transfer-say-message - warm-transfer-say-summary - warm-transfer-twiml - warm-transfer-wait-for-operator-to-speak-first-and-then-say-message - warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary - warm-transfer-experimental message: description: 'This is the message the assistant will deliver to the destination party before connecting the customer. Usage: - Used only when `mode` is `blind-transfer-add-summary-to-sip-header`, `warm-transfer-say-message`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`, or `warm-transfer-experimental`.' oneOf: - type: string - $ref: '#/components/schemas/CustomMessage' timeout: type: number description: 'This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary @default 60' minimum: 1 maximum: 600 default: 60 sipVerb: type: object description: 'This specifies the SIP verb to use while transferring the call. - ''refer'': Uses SIP REFER to transfer the call (default) - ''bye'': Ends current call with SIP BYE - ''dial'': Uses SIP DIAL to transfer the call' default: refer enum: - refer - bye - dial dialTimeout: type: number description: 'This sets the timeout for the dial operation in seconds. This is the duration the call will ring before timing out. Only applicable when `sipVerb=''dial''`. Not applicable for SIP REFER or BYE. @default 60' minimum: 1 maximum: 600 default: 60 holdAudioUrl: type: string description: 'This is the URL to an audio file played while the customer is on hold during transfer. Usage: - Used only when `mode` is `warm-transfer-experimental`. - Used when transferring calls to play hold audio for the customer. - Must be a publicly accessible URL to an audio file. - Supported formats: MP3 and WAV. - If not provided, the default hold audio will be used.' transferCompleteAudioUrl: type: string description: 'This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like ''beep'' to notify that the transfer is complete. Usage: - Used only when `mode` is `warm-transfer-experimental`. - Used when transferring calls to play hold audio for the destination party. - Must be a publicly accessible URL to an audio file. - Supported formats: MP3 and WAV.' contextEngineeringPlan: description: 'This is the plan for manipulating the message context before initiating the warm transfer. Usage: - Used only when `mode` is `warm-transfer-experimental`. - These messages will automatically be added to the transferAssistant''s system message. - If ''none'', we will not add any transcript to the transferAssistant''s system message. - If you want to provide your own messages, use transferAssistant.model.messages instead. @default { type: ''all'' }' oneOf: - $ref: '#/components/schemas/ContextEngineeringPlanLastNMessages' title: Last N Messages - $ref: '#/components/schemas/ContextEngineeringPlanNone' title: None - $ref: '#/components/schemas/ContextEngineeringPlanAll' title: All twiml: type: string description: 'This is the TwiML instructions to execute on the destination call leg before connecting the customer. Usage: - Used only when `mode` is `warm-transfer-twiml`. - Supports only `Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs. - Maximum length is 4096 characters. Example: ``` Hello, transferring a customer to you. They called about billing questions. ```' maxLength: 4096 summaryPlan: description: 'This is the plan for generating a summary of the call to present to the destination party. Usage: - Used only when `mode` is `blind-transfer-add-summary-to-sip-header` or `warm-transfer-say-summary` or `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` or `warm-transfer-experimental`.' allOf: - $ref: '#/components/schemas/SummaryPlan' sipHeadersInReferToEnabled: type: boolean description: 'This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params. @default false' fallbackPlan: description: 'This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human). Usage: - Used only when `mode` is `warm-transfer-experimental`. - If not provided when using `warm-transfer-experimental`, a default message will be used.' allOf: - $ref: '#/components/schemas/TransferFallbackPlan' required: - mode TwilioPhoneNumber: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Twilio. enum: - twilio smsEnabled: type: boolean description: 'Controls whether Vapi sets the messaging webhook URL on the Twilio number during import. If set to `false`, Vapi will not update the Twilio messaging URL, leaving it as is. If `true` or omitted (default), Vapi will configure both the voice and messaging URLs. @default true' default: true id: type: string description: This is the unique identifier for the phone number. orgId: type: string description: This is the unique identifier for the org that this phone number belongs to. createdAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was created. updatedAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was last updated. status: type: string description: This is the status of the phone number. enum: - active - activating - blocked twilioAuthToken: type: string description: This is the Twilio Auth Token for the phone number. twilioApiKey: type: string description: This is the Twilio API Key for the phone number. twilioApiSecret: type: string description: This is the Twilio API Secret for the phone number. name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Twilio. twilioAccountSid: type: string description: This is the Twilio Account SID for the phone number. required: - provider - id - orgId - createdAt - updatedAt - number - twilioAccountSid UpdateByoPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding numberE164CheckEnabled: type: boolean description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which should be used if you know your use case requires it. Use cases: - `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to non-E164 numbers on your SIP trunks. - `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls. If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`). @default true (E164 check is enabled)' default: true name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: This is the number of the customer. minLength: 3 maxLength: 40 credentialId: type: string description: 'This is the credential of your own SIP trunk or Carrier (type `byo-sip-trunk`) which can be used to make calls to this phone number. You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.' UpdateTelnyxPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Telnyx. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. UpdateTwilioPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding smsEnabled: type: boolean description: 'Controls whether Vapi sets the messaging webhook URL on the Twilio number during import. If set to `false`, Vapi will not update the Twilio messaging URL, leaving it as is. If `true` or omitted (default), Vapi will configure both the voice and messaging URLs. @default true' default: true name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Twilio. twilioAccountSid: type: string description: This is the Twilio Account SID for the phone number. twilioAuthToken: type: string description: This is the Twilio Auth Token for the phone number. twilioApiKey: type: string description: This is the Twilio API Key for the phone number. twilioApiSecret: type: string description: This is the Twilio API Secret for the phone number. UpdateVapiPhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' sipUri: type: string description: 'This is the SIP URI of the phone number. You can SIP INVITE this. The assistant attached to this number will answer. This is case-insensitive.' authentication: description: 'This enables authentication for incoming SIP INVITE requests to the `sipUri`. If not set, any username/password to the 401 challenge of the SIP INVITE will be accepted.' allOf: - $ref: '#/components/schemas/SipAuthentication' UpdateVonagePhoneNumberDTO: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Vonage. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. VapiPhoneNumber: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to create free SIP phone numbers on Vapi. enum: - vapi id: type: string description: This is the unique identifier for the phone number. orgId: type: string description: This is the unique identifier for the org that this phone number belongs to. createdAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was created. updatedAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was last updated. status: type: string description: This is the status of the phone number. enum: - active - activating - blocked number: type: string description: These are the digits of the phone number you purchased from Vapi. name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' numberDesiredAreaCode: type: string description: This is the area code of the phone number to purchase. minLength: 3 maxLength: 3 sipUri: type: string description: 'This is the SIP URI of the phone number. You can SIP INVITE this. The assistant attached to this number will answer. This is case-insensitive.' authentication: description: 'This enables authentication for incoming SIP INVITE requests to the `sipUri`. If not set, any username/password to the 401 challenge of the SIP INVITE will be accepted.' allOf: - $ref: '#/components/schemas/SipAuthentication' required: - provider - id - orgId - createdAt - updatedAt VonagePhoneNumber: type: object properties: fallbackDestination: description: 'This is the fallback destination an inbound call will be transferred to if: 1. `assistantId` is not set 2. `squadId` is not set 3. and, `assistant-request` message to the `serverUrl` fails If this is not set and above conditions are met, the inbound call is hung up with an error message.' oneOf: - $ref: '#/components/schemas/TransferDestinationNumber' title: NumberTransferDestination - $ref: '#/components/schemas/TransferDestinationSip' title: SipTransferDestination hooks: type: array description: This is the hooks that will be used for incoming calls to this phone number. items: oneOf: - $ref: '#/components/schemas/PhoneNumberHookCallRinging' title: PhoneNumberHookCallRinging - $ref: '#/components/schemas/PhoneNumberHookCallEnding' title: PhoneNumberHookCallEnding provider: type: string description: This is to use numbers bought on Vonage. enum: - vonage id: type: string description: This is the unique identifier for the phone number. orgId: type: string description: This is the unique identifier for the org that this phone number belongs to. createdAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was created. updatedAt: format: date-time type: string description: This is the ISO 8601 date-time string of when the phone number was last updated. status: type: string description: This is the status of the phone number. enum: - active - activating - blocked name: type: string description: This is the name of the phone number. This is just for your own reference. maxLength: 40 assistantId: type: string description: 'This is the assistant that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' workflowId: type: string description: 'This is the workflow that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' squadId: type: string description: 'This is the squad that will be used for incoming calls to this phone number. If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.' server: description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema. The order of precedence is: 1. assistant.server 2. phoneNumber.server 3. org.server' allOf: - $ref: '#/components/schemas/Server' number: type: string description: These are the digits of the phone number you own on your Vonage. credentialId: type: string description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups. required: - provider - id - orgId - createdAt - updatedAt - number - credentialId