openapi-directory/api/nexmo.com/voice.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","servers":[{"url":"https://api.nexmo.com/v1/calls"}],"info":{"contact":{"email":"devrel@vonage.com","name":"Vonage DevRel","url":"https://developer.nexmo.com/"},"description":"The Voice API lets you create outbound calls, control in-progress calls and get information about historical calls. More information about the Voice API can be found at <https://developer.nexmo.com/voice/voice-api/overview>.","title":"Voice API","version":"1.3.10","x-logo":{"url":"https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg"},"x-origin":[{"format":"openapi","url":"https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/voice.yml","version":"3.0"}],"x-providerName":"nexmo.com","x-serviceName":"voice"},"tags":[{"description":"Fetch, Create and Modify voice calls","name":"Calls"},{"description":"Start or stop streaming audio in to an active call","name":"Stream Audio"},{"description":"Start or stop playing Text to Speech in to an active call","name":"Play TTS"},{"description":"Play DTMF tones in to an active call","name":"Play DTMF"}],"paths":{"/":{"get":{"description":"Get details of your calls","operationId":"getCalls","parameters":[{"description":"Filter by call status","in":"query","name":"status","schema":{"enum":["started","ringing","answered","machine","completed","busy","cancelled","failed","rejected","timeout","unanswered"],"example":"started","type":"string"}},{"description":"Return the records that occurred after this point in time","in":"query","name":"date_start","schema":{"example":"2025-06-15T13:48:44.841Z","format":"date-time","type":"string"}},{"description":"Return the records that occurred before this point in time","in":"query","name":"date_end","schema":{"example":"2025-06-15T13:48:44.841Z","format":"date-time","type":"string"}},{"description":"Return this amount of records in the response","in":"query","name":"page_size","schema":{"default":10,"maximum":100,"minimum":1,"type":"integer"}},{"description":"Return calls from this index in the response","in":"query","name":"record_index","schema":{"default":0,"type":"integer"}},{"description":"Either ascending or  descending order.","in":"query","name":"order","schema":{"default":"asc","enum":["asc","desc"],"type":"string"}},{"description":"Return all the records associated with a specific conversation.","in":"query","name":"conversation_uuid","schema":{"$ref":"#/components/schemas/conversation_uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCallsResponse"}}},"description":"OK"}},"security":[{"bearerAuth":[]}],"summary":"Get details of your calls","tags":["Calls"]},"post":{"description":"Create an outbound Call","operationId":"createCall","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateCallRequestNcco"},{"$ref":"#/components/schemas/CreateCallRequestAnswerUrl"}]}}},"description":"Call Details"},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCallResponse"}}},"description":"Created"}},"security":[{"bearerAuth":[]}],"summary":"Create an outbound call","tags":["Calls"]}},"/{uuid}":{"get":{"description":"Get detail of a specific call","operationId":"getCall","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCallResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Get detail of a specific call","tags":["Calls"]},"parameters":[{"description":"UUID of the Call","example":"63f61863-4a51-4f6b-86e1-46edebcf9356","in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"put":{"description":"Modify an in progress call","operationId":"updateCall","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UpdateCallRequestTransferNcco"},{"$ref":"#/components/schemas/UpdateCallRequestTransferAnswerUrl"},{"$ref":"#/components/schemas/UpdateCallRequestHangup"},{"$ref":"#/components/schemas/UpdateCallRequestMute"},{"$ref":"#/components/schemas/UpdateCallRequestUnmute"},{"$ref":"#/components/schemas/UpdateCallRequestEarmuff"},{"$ref":"#/components/schemas/UpdateCallRequestUnearmuff"}]}}},"required":true},"responses":{"204":{"description":"No Content"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"}},"security":[{"bearerAuth":[]}],"summary":"Modify an in progress call","tags":["Calls"]}},"/{uuid}/dtmf":{"parameters":[{"description":"UUID of the Call Leg","example":"63f61863-4a51-4f6b-86e1-46edebcf9356","in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"put":{"description":"Play DTMF tones into a call","operationId":"startDTMF","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DTMFRequest"}}},"description":"action to perform","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DTMFResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Play DTMF tones into a call","tags":["Play DTMF"]}},"/{uuid}/stream":{"delete":{"description":"Stop playing an audio file into a call","operationId":"stopStream","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopStreamResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Stop playing an audio file into a call","tags":["Stream Audio"]},"parameters":[{"description":"UUID of the Call Leg","example":"63f61863-4a51-4f6b-86e1-46edebcf9356","in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"put":{"description":"Play an audio file into a call","operationId":"startStream","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartStreamRequest"}}},"description":"action to perform","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartStreamResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Play an audio file into a call","tags":["Stream Audio"]}},"/{uuid}/talk":{"delete":{"description":"Stop text to speech in a call","operationId":"stopTalk","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopTalkResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Stop text to speech in a call","tags":["Play TTS"]},"parameters":[{"description":"UUID of the Call Leg","example":"63f61863-4a51-4f6b-86e1-46edebcf9356","in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"put":{"description":"Play text to speech into a call","operationId":"startTalk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartTalkRequest"}}},"description":"Action to perform"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartTalkResponse"}}},"description":"Ok"}},"security":[{"bearerAuth":[]}],"summary":"Play text to speech into a call","tags":["Play TTS"]}}},"components":{"schemas":{"AddressE164":{"description":"The phone number to connect to","example":"14155550100","maxLength":15,"minLength":7,"pattern":"\\d{7,15}","type":"string"},"AddressSip":{"description":"The SIP URI to connect to","example":"sip:rebekka@sip.example.com","maxLength":50,"minLength":1,"type":"string"},"AddressWebsocket":{"example":"wss://example.com/socket","maxLength":50,"minLength":1,"type":"string"},"CreateCallRequestAnswerUrl":{"allOf":[{"required":["answer_url"],"title":"With Answer URL"},{"properties":{"answer_method":{"default":"GET","description":"The HTTP method used to send event information to answer_url.","enum":["POST","GET"],"type":"string"},"answer_url":{"description":"The webhook endpoint where you provide the [Nexmo Call Control Object](/voice/voice-api/ncco-reference) that governs this call.\n","example":["https://example.com/answer"],"items":{"type":"string"},"type":"array","x-nexmo-developer-collection-description-shown":true}}},{"$ref":"#/components/schemas/CreateCallRequestBase"}]},"CreateCallRequestBase":{"properties":{"event_method":{"default":"POST","description":"The HTTP method used to send event information to `event_url`.","enum":["POST","GET"],"type":"string"},"event_url":{"description":"**Required** unless `event_url` is configured at the application\nlevel, see [Create an Application](/api/application.v2#createApplication)\n\nThe webhook endpoint where call progress events are\nsent to. For more information about the values sent, see\n[Event webhook](/voice/voice-api/webhook-reference#event-webhook).\n","example":["https://example.com/event"],"items":{"format":"uri","type":"string"},"type":"array","x-nexmo-developer-collection-description-shown":true},"from":{"$ref":"#/components/schemas/EndpointPhoneFrom"},"length_timer":{"default":7200,"description":"Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.","maximum":7200,"minimum":1,"type":"integer"},"machine_detection":{"description":"Configure the behavior when Vonage detects that the call is answered by voicemail. If `continue`, Vonage sends an HTTP request to `event_url` with the Call event machine. If `hangup`, Vonage ends the call.","enum":["continue","hangup"],"example":"continue","type":"string"},"random_from_number":{"default":false,"description":"Set to `true` to use random phone number as `from`. The number will be selected from the list of the numbers assigned to the current application. `random_from_number: true` cannot be used together with `from`.","type":"boolean"},"ringing_timer":{"default":60,"description":"Set the number of seconds that elapse before Vonage hangs up after the call state changes to ‘ringing’.","maximum":120,"minimum":1,"type":"integer"},"to":{"items":{"oneOf":[{"$ref":"#/components/schemas/EndpointPhoneTo"},{"$ref":"#/components/schemas/EndpointSip"},{"$ref":"#/components/schemas/EndpointWebsocket"},{"$ref":"#/components/schemas/EndpointVBCExtension"}]},"type":"array"}},"required":["to","from"],"type":"object"},"CreateCallRequestNcco":{"allOf":[{"required":["ncco"],"title":"With NCCO"},{"properties":{"ncco":{"description":"The [Nexmo Call Control Object](/voice/voice-api/ncco-reference) to use for this call.\n","example":[{"action":"talk","text":"Hello World"}],"items":{"type":"object"},"type":"array","x-nexmo-developer-collection-description-shown":true}}},{"$ref":"#/components/schemas/CreateCallRequestBase"}]},"CreateCallResponse":{"properties":{"conversation_uuid":{"$ref":"#/components/schemas/conversation_uuid"},"direction":{"$ref":"#/components/schemas/direction"},"status":{"$ref":"#/components/schemas/status"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"DTMFRequest":{"properties":{"digits":{"description":"The digits to send","example":1713,"type":"string"}},"type":"object"},"DTMFResponse":{"properties":{"message":{"description":"Description of the action taken","example":"DTMF sent","type":"string"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"EndpointApp":{"description":"Connect to an App User","properties":{"type":{"description":"The type of connection. Must be `app`","example":"app","type":"string"},"user":{"description":"The username to connect to","example":"jamie","type":"string"}},"required":["type","user"],"type":"object"},"EndpointPhoneFrom":{"description":"Connect to a Phone (PSTN) number","properties":{"number":{"$ref":"#/components/schemas/AddressE164"},"type":{"description":"The type of connection. Must be `phone`","example":"phone","type":"string"}},"required":["number","type"],"type":"object"},"EndpointPhoneTo":{"description":"Connect to a Phone (PSTN) number","properties":{"dtmfAnswer":{"description":"Provide [DTMF digits](https://developer.nexmo.com/voice/voice-api/guides/dtmf) to send when the call is answered","example":"p*123#","type":"string"},"number":{"$ref":"#/components/schemas/AddressE164"},"type":{"description":"The type of connection. Must be `phone`","example":"phone","type":"string"}},"required":["number","type"],"type":"object"},"EndpointSip":{"description":"Connect to a SIP Endpoint","properties":{"type":{"description":"The type of connection. Must be `sip`","example":"sip","type":"string"},"uri":{"$ref":"#/components/schemas/AddressSip"}},"required":["type"],"type":"object"},"EndpointVBCExtension":{"description":"Connect to a VBC extension","properties":{"extension":{"example":"1234","type":"string"},"type":{"description":"The type of connection. Must be `vbc`","example":"vbc","type":"string"}},"required":["type","extension"],"type":"object"},"EndpointWebsocket":{"description":"Connect to a Websocket","properties":{"content-type":{"enum":["audio/l16;rate=8000","audio/l16;rate=16000"],"example":"audio/l16;rate=16000","type":"string"},"headers":{"description":"Details of the Websocket you want to connect to","properties":{"customer_id":{"description":"This is an example header. You can provide any headers you may need","example":"ABC123","type":"string"}},"type":"object"},"type":{"description":"The type of connection. Must be `websocket`","example":"websocket","type":"string"},"uri":{"$ref":"#/components/schemas/AddressWebsocket"}},"required":["type","content-type"],"type":"object"},"GetCallResponse":{"properties":{"_links":{"properties":{"self":{"properties":{"href":{"example":"/calls/63f61863-4a51-4f6b-86e1-46edebcf9356","title":"Link to the Call Object","type":"string"}},"type":"object"}},"type":"object"},"conversation_uuid":{"$ref":"#/components/schemas/conversation_uuid"},"direction":{"$ref":"#/components/schemas/direction"},"duration":{"$ref":"#/components/schemas/duration"},"end_time":{"$ref":"#/components/schemas/end_time"},"from":{"$ref":"#/components/schemas/from"},"network":{"$ref":"#/components/schemas/network"},"price":{"$ref":"#/components/schemas/price"},"rate":{"$ref":"#/components/schemas/rate"},"start_time":{"$ref":"#/components/schemas/start_time"},"status":{"$ref":"#/components/schemas/status"},"to":{"$ref":"#/components/schemas/to"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"GetCallsResponse":{"properties":{"_embedded":{"description":"A list of call objects. See the [get details of a specific call](#getCall) response fields for a description of the nested objects","properties":{"calls":{"items":{"$ref":"#/components/schemas/GetCallResponse"},"type":"array"}},"type":"object"},"_links":{"properties":{"self":{"properties":{"href":{"example":"/calls?page_size=10&record_index=20&order=asc","title":"Link to the object","type":"string"}},"type":"object"}},"type":"object"},"count":{"example":100,"title":"The total number of records returned by your request.","type":"integer"},"page_size":{"example":10,"title":"The amount of records returned in this response.","type":"integer"},"record_index":{"example":0,"title":"The `record_index` used in your request.","type":"integer"}},"type":"object"},"RequestTransferActionParam":{"description":"Transfer the call to a new NCCO","enum":["transfer"],"example":"transfer","type":"string"},"StartStreamRequest":{"properties":{"level":{"default":"0","description":"Set the audio level of the stream in the range `-1 >= level <= 1` with a precision of 0.1. The default value is 0.","example":"0.4","type":"string"},"loop":{"default":1,"description":"the number of times to play the file, 0 for infinite","type":"integer"},"stream_url":{"example":["https://example.com/waiting.mp3"],"items":{"type":"string"},"type":"array","x-nexmo-developer-collection-description-shown":true}},"required":["stream_url"],"type":"object"},"StartStreamResponse":{"properties":{"message":{"description":"Description of the action taken","example":"Stream started","type":"string"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"StartTalkRequest":{"properties":{"language":{"$ref":"#/components/schemas/language"},"level":{"default":"0","description":"The volume level that the speech is played. This can be any value between `-1` to `1` in `0.1` increments, with `0` being the default.","example":"0.4","type":"string"},"loop":{"default":1,"description":"The number of times to repeat the text the file, 0 for infinite","type":"integer"},"premium":{"default":false,"description":"Set to true to use the premium version of the specified style if available, otherwise the standard version will be used. The default value is false. You can find more information about Premium Voices in the [Text-To-Speech guide](/voice/voice-api/guides/text-to-speech#premium-voices).","type":"boolean"},"style":{"$ref":"#/components/schemas/style"},"text":{"description":"The text to read","example":"Hello. How are you today?","type":"string"},"voice_name":{"$ref":"#/components/schemas/voice_name"}},"required":["text"],"type":"object"},"StartTalkResponse":{"properties":{"message":{"description":"Description of the action taken","example":"Talk started","type":"string"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"StopStreamResponse":{"properties":{"message":{"description":"Description of the action taken","example":"Stream stopped","type":"string"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"StopTalkResponse":{"properties":{"message":{"description":"Description of the action taken","example":"Talk stopped","type":"string"},"uuid":{"$ref":"#/components/schemas/uuid"}},"type":"object"},"UpdateCallRequestEarmuff":{"properties":{"action":{"description":"Prevent the specified UUID from hearing audio","enum":["earmuff"],"example":"earmuff","type":"string"}},"title":"Earmuff"},"UpdateCallRequestHangup":{"properties":{"action":{"description":"End the call for the specified UUID","enum":["hangup"],"example":"hangup","type":"string"}},"title":"Hangup"},"UpdateCallRequestMute":{"properties":{"action":{"description":"Mute the specified UUID","enum":["mute"],"example":"mute","type":"string"}},"title":"Mute"},"UpdateCallRequestTransferAnswerUrl":{"properties":{"action":{"$ref":"#/components/schemas/RequestTransferActionParam"},"destination":{"properties":{"type":{"description":"Always `ncco`","example":"ncco","type":"string","x-nexmo-developer-collection-description-shown":true},"url":{"description":"The URL that Vonage makes a request to. Must return an NCCO.","example":["https://example.com/ncco.json"],"items":{"type":"string"},"type":"array","x-nexmo-developer-collection-description-shown":true}},"required":["type","url"],"type":"object"}},"required":["action","destination"],"title":"Transfer with Answer URL","type":"object"},"UpdateCallRequestTransferNcco":{"properties":{"action":{"$ref":"#/components/schemas/RequestTransferActionParam"},"destination":{"properties":{"ncco":{"description":"Refer to the [NCCO Guide](https://developer.nexmo.com/voice/voice-api/ncco-reference) for a description of possible NCCO parameters.","example":[{"action":"talk","text":"Hello World"}],"items":{"type":"object"},"type":"array","x-nexmo-developer-collection-description-shown":true},"type":{"description":"Always `ncco`","example":"ncco","type":"string","x-nexmo-developer-collection-description-shown":true}},"required":["type","ncco"],"type":"object"}},"required":["action","destination"],"title":"Transfer with NCCO","type":"object"},"UpdateCallRequestUnearmuff":{"properties":{"action":{"description":"Allow the specified UUID to hear audio","enum":["unearmuff"],"example":"unearmuff","type":"string"}},"title":"Unearmuff"},"UpdateCallRequestUnmute":{"properties":{"action":{"description":"Unmute the specified UUID","enum":["mute"],"example":"unmute","type":"string"}},"title":"Unmute"},"conversation_uuid":{"description":"The unique identifier for the conversation this call leg is part of.","example":"CON-f972836a-550f-45fa-956c-12a2ab5b7d22","format":"uuid","title":"The UUID of the Conversation","type":"string"},"direction":{"description":"Possible values are `outbound` or `inbound`","enum":["outbound","inbound"],"example":"outbound","type":"string"},"duration":{"description":"The time elapsed for the call to take place in seconds. This is only sent if `status` is `completed`.","example":"60","title":"The Duration of the call ","type":"string"},"end_time":{"description":"The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For xample, `2020-01-01 12:00:00`. This is only sent if `status` is `completed`.","example":"2025-06-15T13:48:44.842Z","format":"timestamp","title":"The End Time of the call ","type":"string"},"from":{"description":"The endpoint you called from. Possible values are the same as `to`.","properties":{"number":{"example":"447700900001","title":"The number that made the call","type":"string"},"type":{"example":"phone","title":"The type of Endpoint that made the call","type":"string"}},"type":"object"},"language":{"default":"en-US","description":"The language to use","enum":["ar","ca-ES","cmn-CN","cmn-TW","cs-CZ","cy-GB","da-DK","de-DE","el-GR","en-AU","en-GB","en-GB-WLS","en-IN","en-US","en-ZA","es-ES","es-MX","es-US","eu-ES","fi-FI","fil-PH","fr-CA","fr-FR","he-IL","hi-IN","hu-HU","id-ID","is-IS","it-IT","ja-JP","ko-KR","nb-NO","nl-NL","no-NO","pl-PL","pt-BR","pt-PT","ro-RO","ru-RU","sk-SK","sv-SE","th-TH","tr-TR","uk-UA","vi-VN","yue-CN"],"type":"string"},"network":{"description":"The Mobile Country Code Mobile Network Code ([MCCMNC](https://en.wikipedia.org/wiki/Mobile_country_code)) for the carrier network used to make this call. This is only sent if `status` is `completed`.","example":"65512","title":"The Network ID of the destination ","type":"string"},"price":{"description":"The total price charged for this call. This is only sent if `status` is `completed`.","example":"23.40","title":"The total price of the call ","type":"string"},"rate":{"description":"The price per minute for this call. This is only sent if `status` is `completed`.","example":"0.39","title":"The Price per minute of the called destination","type":"string"},"start_time":{"description":"The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For example, `2020-01-01 12:00:00`. This is only sent if `status` is `completed`.","example":"2025-06-15T13:48:44.842Z","format":"timestamp","title":"The Start Time of the call ","type":"string"},"status":{"description":"The status of the call. [See possible values](https://developer.nexmo.com/voice/voice-api/guides/call-flow#event-objects)","example":"completed","title":"The State of the call","type":"string"},"style":{"default":0,"description":"The vocal style (vocal range, tessitura, and timbre) to use","type":"integer"},"to":{"description":"The single or mixed collection of endpoint types you connected to","properties":{"number":{"example":"447700900000","title":"The number of the endpoint called","type":"string"},"type":{"example":"phone","title":"The Type of Endpoint Called","type":"string"}},"type":"object"},"uuid":{"description":"The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls","example":"63f61863-4a51-4f6b-86e1-46edebcf9356","format":"uuid","title":"The UUID of the Call Leg","type":"string"},"voice_name":{"default":"Kimberly","deprecated":true,"description":"<strong>DEPRECATED</strong> The voice & language to use","enum":["Aditi","Agnieszka","Alva","Amy","Astrid","Bianca","Brian","Carla","Carmen","Carmit","Catarina","Celine","Cem","Chantal","Chipmunk","Conchita","Cristiano","Damayanti","Dora","Emma","Empar","Enrique","Eric","Ewa","Felipe","Filiz","Geraint","Giorgio","Gwyneth","Hans","Henrik","Ines","Ioana","Iveta","Ivy","Jacek","Jan","Jennifer","Joana","Joanna","Joey","Jordi","Justin","Kanya","Karl","Kendra","Kimberly","Laila","Laura","Lea","Lekha","Liv","Lotte","Lucia","Luciana","Mads","Maged","Maja","Mariska","Marlene","Mathieu","Matthew","Maxim","Mei-Jia","Melina","Mia","Miguel","Miren","Mizuki","Montserrat","Naja","Nicole","Nikos","Nora","Oskar","Penelope","Raveena","Ricardo","Ruben","Russell","Salli","Satu","Seoyeon","Sin-Ji","Sora","Takumi","Tarik","Tatyana","Tessa","Tian-Tian","Vicki","Vitoria","Yelda","Zeina","Zhiyu","Zuzana"],"type":"string"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}}}