openapi: 3.0.0 info: version: 1.0.0 title: Text-to-call API contact: name: Apifonica Support email: support@apifonica.com x-logo: url: 'https://apifonica.com/public/img/logo.svg' altText: Apifonica logo description: |- ## Description You are looking at text-to-call API service documentation. This service allows you to transform text messages into voice calls. The service supports 4 text-to-speech engines which can operate under the hood: 1. Amazon 1. Azure 1. Google 1. Yandex Each engine itself has its own set of available supported languages and corresponding voices. You also are in charge of controlling the speed of generated speech. Voice speed limits also differ from engine to engine. Service allows you to schedule voice call retries for busy recipients making up to 10 attempts within customizable timeframes. ## Usage ##### PRECONDITIONS You have to be a registered Apifonica user to use this service: 1. Register an Apifonica account at (https://apifonica.com/) 1. Get `account_sid` and `account_token` in your personal account profile (https://account.apifonica.com/profile). You will need them for API request authentication. 1. Rent any voice-supporting phone number (type must be `landline` or `mobile`): https://account.apifonica.com/numbers/buy. ##### USER FLOW 1. Create account settings using [Account Settings API](#tag/AccountSettings). 1. Make a voice call request using [Communication API](#tag/Communication). Please, mind that creation of account settings creates an application in the [Application](https://account.apifonica.com/voice-settings/applications) section. It is a webhook for our call system to know where to send the call events at (such as `answered`, `failed` and etc.). After automatic creation of application the text-to-call service would be able to catch event. Accident application deletion or specific change in Events dropdown field will result in text-to-call service stop working - you will have to manually create application with parameters: - Name: any name you want - Method: POST - Controller: https://ttc.apifonica.com/event/text-to-call - Events: All servers: - url: 'https://ttc.apifonica.com' tags: - name: AccountSettings description: |- The Account Settings API defines process of creation, getting, updating, deleting account settings used as default for voice generation. It contains 4 endpoints - each responsible for corresponding CRUD operation with account settings. `engine`, `voice` and `language` are required attributes in JSON body request. You can check out schema itself and examples right below. This step simplifies process of further text-to-call request. List of available voice types and languages depends on the engine. Here are links to the documentation: 1. Amazon (polly) engine: https://docs.aws.amazon.com/en_us/polly/latest/dg/voicelist.html 1. Azure engine: https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=tts 1. Google engine: https://cloud.google.com/text-to-speech/docs/voices 1. Yandex engine: https://cloud.yandex.com/en/docs/speechkit/tts/voices `speed` attribute is optional, however you can set it if you want. It is a float value in a string format. By default it will be set to `"1.0"` which means normal voice speed. If combination of `engine`, `voice`, `language`, `speed` is not valid (not supported by chosen engine) - you will get a validation error as a response. - name: Communication description: |- Communication API defines process of making a call with corresponding text, voice settings and retry schedule. Basically there are 3 requires attributes here: `from`, `to`, `text`. You can then override some voice settings if you don't want to use those which are set in your account settings. Those are `engine`, `voice`, `language`, `speed`. If you omit any of these - it will be taken from account settings. If final combination of `engine`, `voice`, `language`, `speed` with all overrides is not valid (not supported by chosen engine) - you will get a validation error as a response. F. e. imagine you have in your account settings: `engine` = `"polly"`, `voice` = `"Aria"`, `language` = `"en-NZ"`, `speed` = `"1.0"`. Meanwhile in your request you have set: `voice` = `"Gregory"`, `language` = `"en-US"`. Final voice settings which will be used to generate voice message will be: `engine` = `"polly"`, `voice` = `"Gregory"`, `language` = `"en-US"`, `speed` = `"1.0"`. Optionally you can set `retry_schedule` attribute in a JSON request body (see the scheme below). If set this array of items must contain from 1 to 10 values including both limits. Each element is set in minutes, must be a positive integer and be not bigger than 1440. F.e. you can set retry schedule to be `[1, 2]` which means following: if first initial voice call will fail - second voice call try will be initiated after 1 minute since service catches unsuccessful event (`no answer`, `cancelled`, `busy`, `rejected`, `failed`). If second try turns out to be unsuccessful either - third try will be initiated since 2 minutes after service catches unsuccessful event. Third try will be the last no matter the outcome - success or failure. All voice settings will be the same for all tries. paths: /settings: post: tags: - AccountSettings summary: Create account settings description: |- Use this endpoint to create account settings. operationId: createAccountSettings security: - basicAuth: [] requestBody: description: '' content: application/json: schema: $ref: components/request/account_settings_request.yaml examples: Polly example: value: engine: polly voice: Ines language: pt-PT Google example with speed: value: engine: google voice: en-US-Standard-A language: en-US speed: '1.1' responses: '201': description: Created content: application/json: schema: $ref: components/response/account_settings_response.yaml examples: Polly example: value: engine: polly voice: Ines language: pt-PT speed: '1.0' Google example with speed: value: engine: google voice: en-US-Standard-A language: en-US speed: '1.1' '400': description: Bad Request content: application/json: schema: $ref: components/response/error.yaml examples: Invalid character in request body: value: code: ERR001 reason: Bad request - The request could not be understood by the service due to malformed syntax message: invalid character '1' after object key:value pair Invalid set of engine-voice-language: value: code: ERR011 reason: Resource validation failed message: "failed validating account settings: [engine=polly], [voice=IncorrectVoice], [language=pt-PT], [speed=1.0 (default)]" '401': description: Unauthorized content: application/json: schema: $ref: components/response/error.yaml examples: No credentials provided: value: code: ERR204 reason: Authentication Error - No credentials provided message: Your AccountSid or AuthToken was incorrect. '403': description: Not Authorized content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR201 reason: Authentication Error - account_sid or account_token was incorrect message: You don’t have necessary permissions for the resource. '409': description: Resource Conflict content: application/json: schema: $ref: components/response/error.yaml examples: Account settings already exist: value: code: ERR013 reason: Resource conflict message: account settings for accountSid=acc89ddf772-5df2-41d7-b257-000000000000 already exist '500': description: Runtime Error Unknown content: application/json: schema: $ref: components/response/error.yaml examples: Storage error: value: code: ERR021 reason: Runtime error while storing resource message: Storage error message Unexpected error: value: code: ERR003 reason: Runtime error - The service encountered an unexpected condition which prevented it from fulfilling your request message: Unexpected error message get: tags: - AccountSettings summary: Get account settings description: |- Use this endpoint to get account settings. operationId: getAccountSettings security: - basicAuth: [ ] responses: '200': description: OK content: application/json: schema: $ref: components/response/account_settings_response.yaml examples: Polly example: value: engine: polly voice: Ines language: pt-PT speed: '1.0' Google example with speed: value: engine: google voice: en-US-Standard-A language: en-US speed: '1.1' '401': description: Unauthorized content: application/json: schema: $ref: components/response/error.yaml examples: No credentials provided: value: code: ERR204 reason: Authentication Error - No credentials provided message: Your AccountSid or AuthToken was incorrect. '403': description: Not Authorized content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR201 reason: Authentication Error - account_sid or account_token was incorrect message: You don’t have necessary permissions for the resource. '404': description: Resource Not Found content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR012 reason: Resource not found message: account settings for accountSid=acc89ddf772-5df2-41d7-b257-000000000000 not found '500': description: Runtime Error Unknown content: application/json: schema: $ref: components/response/error.yaml examples: Storage error: value: code: ERR021 reason: Runtime error while fetching resources message: Storage error message Unexpected error: value: code: ERR003 reason: Runtime error - The service encountered an unexpected condition which prevented it from fulfilling your request message: Unexpected error message put: tags: - AccountSettings summary: Update account settings description: |- Use this endpoint to update account settings. operationId: updateAccountSettings security: - basicAuth: [] requestBody: description: '' content: application/json: schema: $ref: components/request/account_settings_request.yaml examples: Polly example: value: engine: polly voice: Ines language: pt-PT Google example with speed: value: engine: google voice: en-US-Standard-A language: en-US speed: '1.1' responses: '200': description: OK content: application/json: schema: $ref: components/response/account_settings_response.yaml examples: Polly example: value: engine: polly voice: Ines language: pt-PT speed: '1.0' Google example with speed: value: engine: google voice: en-US-Standard-A language: en-US speed: '1.1' '400': description: Bad Request content: application/json: schema: $ref: components/response/error.yaml examples: Invalid character in request body: value: code: ERR001 reason: Bad request - The request could not be understood by the service due to malformed syntax message: invalid character '1' after object key:value pair Invalid set of engine-voice-language: value: code: ERR011 reason: Resource validation failed message: "failed validating account settings: [engine=polly], [voice=IncorrectVoice], [language=pt-PT], [speed=1.0 (default)]" '401': description: Unauthorized content: application/json: schema: $ref: components/response/error.yaml examples: No credentials provided: value: code: ERR204 reason: Authentication Error - No credentials provided message: Your AccountSid or AuthToken was incorrect. '403': description: Not Authorized content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR201 reason: Authentication Error - account_sid or account_token was incorrect message: You don’t have necessary permissions for the resource. '404': description: Resource Not Found content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR012 reason: Resource not found message: account settings for accountSid=acc89ddf772-5df2-41d7-b257-000000000000 not found '500': description: Runtime Error Unknown content: application/json: schema: $ref: components/response/error.yaml examples: Storage error: value: code: ERR021 reason: Runtime error while updating resource message: Storage error message Unexpected error: value: code: ERR003 reason: Runtime error - The service encountered an unexpected condition which prevented it from fulfilling your request message: Unexpected error message delete: tags: - AccountSettings summary: Delete account settings description: |- Use this endpoint to delete account settings. operationId: deleteAccountSettings security: - basicAuth: [ ] responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: $ref: components/response/error.yaml examples: No credentials provided: value: code: ERR204 reason: Authentication Error - No credentials provided message: Your AccountSid or AuthToken was incorrect. '403': description: Not Authorized content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR201 reason: Authentication Error - account_sid or account_token was incorrect message: You don’t have necessary permissions for the resource. '404': description: Resource Not Found content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR012 reason: Resource not found message: account settings for accountSid=acc89ddf772-5df2-41d7-b257-000000000000 not found '500': description: Runtime Error Unknown content: application/json: schema: $ref: components/response/error.yaml examples: Storage error: value: code: ERR021 reason: Runtime error while remove resource message: Storage error message Unexpected error: value: code: ERR003 reason: Runtime error - The service encountered an unexpected condition which prevented it from fulfilling your request message: Unexpected error message /voice-message: post: tags: - Communication summary: Make a call with voice message description: |- Use this endpoint to make a call with text and speech settings if need to override account settings ones. operationId: makeCall security: - basicAuth: [] requestBody: description: '' content: application/json: schema: $ref: components/request/communication_request.yaml examples: Simple voice message: value: from: '4800000000' to: '4800000001' text: Test message responses: '201': description: Created content: application/json: schema: $ref: components/response/communication_response.yaml examples: Response example: value: uri: https://api.apifonica.com/v2/accounts/acc89ddf772-5df2-41d7-b257-000000000000/calls/cal59544545-c9d2-463d-ae02-000000000000 speech_request_sid: 6a186633-e655-4e23-5a52-000000000000 call_sid: cal59544545-c9d2-463d-ae02-000000000000 '400': description: Bad Request content: application/json: schema: $ref: components/response/error.yaml examples: Invalid character in request body: value: code: ERR001 reason: Bad request - The request could not be understood by the service due to malformed syntax message: invalid character '1' after object key:value pair Invalid set of engine-voice-language: value: code: ERR011 reason: Resource validation failed message: "error validating speech settings, consisting of set: [engine=polly], [voice=Gregory], [language=en-US], [speed=speed=1.0 (taken from account settings)]" '401': description: Unauthorized content: application/json: schema: $ref: components/response/error.yaml examples: No credentials provided: value: code: ERR204 reason: Authentication Error - No credentials provided message: Your AccountSid or AuthToken was incorrect. '403': description: Not Authorized content: application/json: schema: $ref: components/response/error.yaml examples: Incorrect credentials: value: code: ERR201 reason: Authentication Error - account_sid or account_token was incorrect message: You don’t have necessary permissions for the resource. '500': description: Runtime Error Unknown content: application/json: schema: $ref: components/response/error.yaml examples: Storage error: value: code: ERR021 reason: Runtime error while fetching resource message: Storage error message Unexpected error: value: code: ERR003 reason: Runtime error - The service encountered an unexpected condition which prevented it from fulfilling your request message: Unexpected error message '502': description: Bad Gateway content: application/json: schema: $ref: components/response/error.yaml examples: Platform API error: value: code: ERR502 reason: A third party system error occurred while interaction message: Platform API error components: securitySchemes: basicAuth: type: http scheme: basic description: | * `Username` - equal to your `account_sid` (e.g., acc89ddf772-5df2-41d7-b257-000000000000) * `Password` - equal to your `account_token` (e.g., auta42e0580-8138-308a-a354-000000000000)