{"openapi":"3.0.0","info":{"title":"Engage API (Voice)","version":"2.0","description":"The Telesign Voice endpoints of the Engage API.","contact":{"name":"Telesign Customer Support Team","email":"support@telesign.com"}},"servers":[{"url":"https://rest-ww.telesign.com/v2"}],"paths":{"/voice":{"post":{"summary":"Send an action","operationId":"sendVoiceAction","responses":{"200":{"$ref":"#/components/responses/resVoice200"},"202":{"$ref":"#/components/responses/resVoice202"},"400":{"$ref":"#/components/responses/resVoice400"},"401":{"$ref":"#/components/responses/resVoice401"},"429":{"$ref":"#/components/responses/resVoice429"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Action"},"examples":{"Example":{"value":{"method":"dial","params":{"to":"15555551212","caller_id_number":"15554441313","send_dtmf":"6458","external_id":"4142b474-d65d-4265-a5fa-a581b1fe6101","is_primary":true}}}}}}},"description":"Send an action to Telesign Voice. For more details on the object structure of each specific action type, see the *[Voice - Actions](/enterprise/reference/voice-actions)* page.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) (easiest to implement) or [Digest](/enterprise/docs/authentication#digest-authentication)\n* **Protocols:** HTTPS\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Accepts:** `application/json` (use [JSON-RPC](http://www.jsonrpc.org/specification) format) \n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)","tags":["Voice"]}},"/call_recording":{"get":{"summary":"Get recordings list by date range","tags":["Recordings"],"responses":{"200":{"description":"**Success.** A list of recordings was successfully retrieved.","content":{"application/json":{"schema":{"type":"object","properties":{"call_recordings":{"$ref":"#/components/schemas/Recording"},"token":{"type":"string","description":"An arbitrary string you can include in your next request to the API, to return the next page of results.","example":"Z0FBQUFBQmRTM01KYUtpQUlRc0FNcEpuMjczYmlZcC1CMlZVe"}}},"examples":{"Example":{"value":{"call_recordings":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","file_name":"0123456789ABCDEF0123456789ABCDEF_1631039244.wav","status":"available","date":"2021-09-07T18:27:24"},"token":"Z0FBQUFBQmRTM01KYUtpQUlRc0FNcEpuMjczYmlZcC1CMlZVe"}}}}}},"400":{"description":"**Bad Request.** Your request contains invalid parameters, contains mutually exclusive parameters, or is missing required parameters. If you included `start_date_time` and `end_date_time`, check that their values were in proper UTC format, and that `token` was not included. If you included `token`, check that its value was a valid token from a previous request to this API, and that `start_date_time` and `end_date_time` were not included."},"401":{"$ref":"#/components/responses/resCRRShared401"},"404":{"$ref":"#/components/responses/resCRRShared404"}},"operationId":"getRecordingsListByDateRange","parameters":[{"schema":{"type":"string","example":"2019-04-01T03:00:00"},"in":"query","name":"start_date_time","description":"A timestamp defining the beginning of the date range (inclusive). If you include this, you must also include the `end_date_time` param, and must not include `token`."},{"schema":{"type":"string","example":"2019-04-02T23:00:00"},"in":"query","name":"end_date_time","description":"A timestamp defining the end of the date range (inclusive). If you include this, you must also include the `start_date_time` param, and must not include `token`."},{"schema":{"type":"string","maxLength":100,"example":"10"},"in":"query","name":"pagesize","description":"The number of records to return per page."},{"schema":{"type":"string"},"in":"query","name":"token","description":"Indicates to the service at which page of records to begin retrieval. Found in your previous request to the API. If you include this, you must not include either the `start_date_time` or the `end_date_time` params."}],"description":"Retrieve a list of recordings by date range. Each record includes a reference ID that you can use with other Recordings actions.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) \n* **Protocols:** HTTPS\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)"}},"/call_recording/{reference_id}":{"parameters":[{"$ref":"#/components/parameters/reference_id"}],"get":{"summary":"Retrieve a list of recordings for a call","tags":["Recordings"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecordingWithDetail"}},"examples":{"Example":{"value":[{"reference_id":"0123456789ABCDEF0123456789ABCDEF","file_name":"0123456789ABCDEF0123456789ABCDEF_1631039244.wav","status":"available","date":"2021-09-07T18:27:24","url":"https://call-recording-stg.tlsn.io/call_recording/D596D7B0D1800164898350B4E71B005C_1631039244.wav?Expires=1631043688&Signature=Jm-Y-qPZMMTbnye-NumQETh~5mNGd6PBRKURKXqeiqj44WeFaKzbdiyXln6ijXff409Srdqme0527mKU15CMuEQXepPeNI64m-ovtt6faE1TbRCa6zHaWeO2dcZM4XYCrILtsgi~j0S5Jj0~PnDMpGXw1XEFOKU55B2o-~asXkxbo-WniO9R8fGV8AHAATwON5roEmxJHNfT1oujq6M3Tq-CNwd46jEhf2tLuVdC1h1XTeHx6UATHPLw3shTPafR3iQ8PP9T8qjWQucoWuAUh5Y7WtDS6U3HMGkOC2QzveHpbA1RNaQMCqT~TvrCtTwEaQr7W~YD82mPwESr9DlRUg__&Key-Pair-Id=APKAJ2B7QX7EM7MEC7SA","transcribe":{"language_code":"en-US","transcription":[{"status":"completed","result":"Welcome to Vero-Finto's customer service line. To better assist you with your issue, please state your name."}]}}]}}}}},"400":{"$ref":"#/components/responses/resCRRByID400"},"401":{"$ref":"#/components/responses/resCRRShared401"},"404":{"$ref":"#/components/responses/resCRRShared404"}},"operationId":"getRecordingsListByCallID","description":"Retrieve a list of recordings associated with the specified call. Each record includes a URL that can be used to download the recording, if available.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) \n* **Protocols:** HTTPS\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)"},"delete":{"summary":"Delete recordings by ID","operationId":"deleteRecordings","responses":{"204":{"description":"**Success.** Recordings and transcripts deleted, if authorized."},"400":{"$ref":"#/components/responses/resCRRByID400"},"401":{"$ref":"#/components/responses/resCRRShared401"},"404":{"$ref":"#/components/responses/resCRRShared404"},"503":{"description":"**Deletion Failure.** One or more of the files you attempted to delete could not be deleted. The response payload lists which files were deleted and which were not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFailureDetails"},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","failed_delete":["0123456789ABCDEF0123456789ABCDEF_1631039233.wav"],"succeed_delete":["0123456789ABCDEF0123456789ABCDEF_1631039234.wav"]}}}}}}},"description":"Delete all recordings and transcripts associated with the call specified by this reference ID.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) \n* **Protocols:** HTTPS\n* **Endpoint:** `https://rest-ww.telesign.com/call_recording/{reference_id}`\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)","tags":["Recordings"]}}},"components":{"schemas":{"Action":{"title":"Action","type":"object","properties":{"method":{"type":"string","description":"The type of the action included in this request.","example":"dial"},"params":{"type":"object","description":"Contains sub-properties associated with this action type. For more details on the object structure of each specific action type, see the *[Voice - Actions](/enterprise/reference/voice-actions)* page."}}},"Recording":{"title":"Recording","type":"object","properties":{"reference_id":{"type":"string","description":"Specifies the Telesign Voice call for which you want to retrieve or delete recordings.","example":"0123456789ABCDEF0123456789ABCDEF"},"file_name":{"type":"string","description":"The name of this call record file. If the recording is still in progress, this property does not appear.","example":"0123456789ABCDEF0123456789ABCDEF_1631039244.wav"},"status":{"type":"string","example":"available","description":"The status of the recording. Possible values are:<br/>* `recording` - The call recording is still in progress. It is not yet available for retrieval.<br/>* `available` - The call recording is complete and available for retrieval.<br/>* `deleted` - The call recording has been deleted and is not available for retrieval."},"date":{"type":"string","description":"The UTC+0 date when the recording was created. It follows this format: {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}.","example":"2021-09-07T18:27:24"}}},"RecordingWithDetail":{"title":"RecordingWithDetail","allOf":[{"$ref":"#/components/schemas/Recording"},{"type":"object","properties":{"url":{"type":"string","description":"A full URL you can use to download the call recording. If the recording is still in progress, this property does not appear.","example":"https://call-recording-stg.tlsn.io/call_recording/D596D7B0D1800164898350B4E71B005C_1631039244.wav?Expires=1631043688&Signature=Jm-Y-qPZMMTbnye-NumQETh~5mNGd6PBRKURKXqeiqj44WeFaKzbdiyXln6ijXff409Srdqme0527mKU15CMuEQXepPeNI64m-ovtt6faE1TbRCa6zHaWeO2dcZM4XYCrILtsgi~j0S5Jj0~PnDMpGXw1XEFOKU55B2o-~asXkxbo-WniO9R8fGV8AHAATwON5roEmxJHNfT1oujq6M3Tq-CNwd46jEhf2tLuVdC1h1XTeHx6UATHPLw3shTPafR3iQ8PP9T8qjWQucoWuAUh5Y7WtDS6U3HMGkOC2QzveHpbA1RNaQMCqT~TvrCtTwEaQr7W~YD82mPwESr9DlRUg__&Key-Pair-Id=APKAJ2B7QX7EM7MEC7SA"},"transcribe":{"type":"object","description":"Contains properties related to the transcript for this recording. This package is only present if a transcript was made.","properties":{"language_code":{"type":"string","description":"A code indicating the language you set for the transcription.","example":"en-US"},"transcription":{"type":"array","description":"Contains additional properties related to the transcript.","items":{"$ref":"#/components/schemas/Transcription"}}}}}}]},"Transcription":{"title":"Transcription","type":"object","description":"Contains additional properties related to the transcript.","properties":{"status":{"type":"string","description":"The status of generating the transcript. Note that there is a delay of up to a few seconds between completion of the call recording and completion of the transcript.","example":"completed"},"result":{"type":"string","description":"The text transcript of this call recording. If the recording has been deleted, this property is not returned.","example":"Welcome to Vero-Finto's customer service line. To better assist you with your issue, please state your name."}}},"DeleteFailureDetails":{"title":"DeleteFailureDetails","type":"object","properties":{"reference_id":{"type":"string","description":"Specifies the Telesign Voice call for which you want to retrieve or delete recordings.","example":"0123456789ABCDEF0123456789ABCDEF"},"failed_delete":{"type":"array","description":"Each element in this array contains the name of a file that could not be deleted.","items":{"type":"string","example":"0123456789ABCDEF0123456789ABCDEF_1631039233.wav"}},"succeed_delete":{"type":"array","description":"Each element in this array contains the name of a file that was successfully deleted. If no files were successfully deleted, this property is not returned.","items":{"type":"string","example":"0123456789ABCDEF0123456789ABCDEF_1631039234.wav"}}},"required":["failed_delete"]},"VoiceStatus":{"title":"VoiceStatus","type":"object","properties":{"reference_id":{"type":"string","description":"A Telesign ID that uniquely identifies this Voice session.","example":"0123456789ABCDEF0123456789ABCDEF"},"status":{"type":"string","description":"The current state of the session, after processing the action from your request."}}}},"securitySchemes":{"Basic":{"type":"http","scheme":"basic"}},"responses":{"resVoice200":{"description":"The request was successfully processed, but the service could not complete the action.\n\n|Error string | Description|\n|--|--|\n| `premium_to_number_rejected` | Phone number (`to`) in the request has the unsupported number type \\\"premium\\\". Action rejected. |\n| `to_number_blocked_by_country` | Phone number (`to`) in the request is blocked based on its country of origin. Blocked countries can be specified either by you in the customer portal, or by Telesign. Action rejected. |\n| `to_number_blocked_by_customer` | Phone number (`to`) in the request is on the blocked list in the customer portal. Action rejected.|\n| `to_number_blocked_by_telesign` | Phone number (`to`) in the request is blocked by Telesign for all requests. Action rejected. |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VoiceStatus"},{"type":"object","properties":{"status":{"type":"string","example":"premium_to_number_rejected"}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","status":"premium_to_number_rejected"}}}}}},"resVoice400":{"description":"|Error string|Description|\n|--|--|\n| `caller_id_number_not_owned` | Virtual number (`caller_id_number`) in the request is not owned by you. Action rejected. |\n| `caller_id_number_not_provided` | Request does not include a virtual number (`caller_id_number`). Action rejected. |\n| `invalid_phone_number` | Phone number (`to`) in the request is invalid. Action rejected. |\n| `to_number_not_provided` | Request does not include a phone number (`to`). Action rejected. |\n| `unsupported_call_state` | Action in the request is not supported for current call state, or not supported at all for this event. Action rejected. | ","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VoiceStatus"},{"type":"object","properties":{"status":{"type":"string","example":"caller_id_number_not_owned"}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","status":"caller_id_number_not_owned"}}}}}},"resVoice401":{"description":"|Error string|Description|\n|--|--|\n| `credentials_not_provided` | Customer ID and/or API key missing from the authorization header of the request. Action rejected.|\n| `not_authorized` | Could not authenticate with the Customer ID and API key in the authorization header of the request. Action rejected. |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VoiceStatus"},{"type":"object","properties":{"status":{"type":"string","example":"credentials_not_provided"}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","status":"credentials_not_provided"}}}}}},"resVoice429":{"description":"|Error string|Description|\n|--|--|\n| `rate_limit_exceeded` | Account has exceeded rate limit for either outbound or inbound requests. Action rejected. |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VoiceStatus"},{"type":"object","properties":{"status":{"type":"string","example":"rate_limit_exceeded"}}}]},"examples":{"Example 1":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","status":"rate_limit_exceeded"}}}}}},"resCRRByID400":{"description":"**Bad Request.** Your request contains invalid parameters or is missing required parameters. Check that you've included a valid `reference_id` for a Telesign Voice phone call in the path.","content":{}},"resCRRShared401":{"description":"**Unauthorized.** Customer ID and/or API Key were not provided or were not valid.","content":{}},"resCRRShared404":{"description":"**Not Found.** No records were found matching the details of your request.","content":{}},"resVoice202":{"description":"**Success.** The request was successfully processed and the action was successfully taken.\n\nStatus string|Description\n--|--\n`dial_accepted`|The dial action was completed successfully and the end user answered the call.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VoiceStatus"},{"type":"object","properties":{"status":{"type":"string","example":"dial_accepted"},"external_id":{"type":"string","example":"4142b474-d65d-4265-a5fa-a581b1fe6101","description":"An identifier generated by you and included in this request. If you did not include an external ID in the request, this property is not included."}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","status":"dial_accepted","external_id":"4142b474-d65d-4265-a5fa-a581b1fe6101"}}}}}}},"parameters":{"reference_id":{"name":"reference_id","in":"path","required":true,"schema":{"type":"string"},"description":"Specifies the call for which you want to retrieve or delete recordings. This ID is returned in the HTTP response to the `dial` action that begins an outbound call or in the `incoming_call` event for an inbound call."}}},"security":[{"Basic":[]}],"tags":[{"name":"Recordings"},{"name":"Voice"}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}