Package com.nexmo.client.voice
Class VoiceClient
- java.lang.Object
-
- com.nexmo.client.AbstractClient
-
- com.nexmo.client.voice.VoiceClient
-
public class VoiceClient extends AbstractClient
A client for talking to the Nexmo Voice API. The standard way to obtain an instance of this class is to useNexmoClient.getVoiceClient().
-
-
Field Summary
Fields Modifier and Type Field Description protected com.nexmo.client.voice.CallsEndpointcallsprotected com.nexmo.client.voice.DownloadRecordingEndpointdownloadRecordingprotected DtmfEndpointdtmfprotected com.nexmo.client.voice.StreamsEndpointstreamsprotected TalkEndpointtalk-
Fields inherited from class com.nexmo.client.AbstractClient
httpWrapper
-
-
Constructor Summary
Constructors Constructor Description VoiceClient(HttpWrapper httpWrapper)Constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description CallEventcreateCall(Call callRequest)Begin a call to a phone number.RecordingdownloadRecording(java.lang.String recordingUrl)Download a recording, given the recordingUrl provided from the webhook callback.CallInfogetCallDetails(java.lang.String uuid)Look up the status of a single call initiated bycreateCall(Call).CallInfoPagelistCalls()Obtain the first page of CallInfo objects, representing the most recent calls initiated bycreateCall(Call).CallInfoPagelistCalls(CallsFilter filter)Obtain the first page of CallInfo objects matching the query described byfilter, representing the most recent calls initiated bycreateCall(Call).ModifyCallResponsemodifyCall(CallModifier modifier)Modify an ongoing call using a CallModifier object.ModifyCallResponsemodifyCall(java.lang.String uuid, ModifyCallAction action)Modify an ongoing call.DtmfResponsesendDtmf(java.lang.String uuid, java.lang.String digits)Send DTMF codes to an ongoing call.StreamResponsestartStream(java.lang.String uuid, java.lang.String streamUrl)Stream audio to an ongoing call.StreamResponsestartStream(java.lang.String uuid, java.lang.String streamUrl, int loop)Stream audio to an ongoing call.TalkResponsestartTalk(java.lang.String uuid, java.lang.String text)Send a synthesized speech message to an ongoing call.TalkResponsestartTalk(java.lang.String uuid, java.lang.String text, int loop)Send a synthesized speech message to an ongoing call.TalkResponsestartTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName)Send a synthesized speech message to an ongoing call.TalkResponsestartTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName, int loop)Send a synthesized speech message to an ongoing call.StreamResponsestopStream(java.lang.String uuid)Stop the audio being streamed into a call.TalkResponsestopTalk(java.lang.String uuid)Stop the message being spoken into a call.ModifyCallResponsetransferCall(java.lang.String uuid, java.lang.String nccoUrl)Transfer a call to a different NCCO endpoint.
-
-
-
Field Detail
-
calls
protected final com.nexmo.client.voice.CallsEndpoint calls
-
streams
protected final com.nexmo.client.voice.StreamsEndpoint streams
-
talk
protected final TalkEndpoint talk
-
dtmf
protected final DtmfEndpoint dtmf
-
downloadRecording
protected final com.nexmo.client.voice.DownloadRecordingEndpoint downloadRecording
-
-
Constructor Detail
-
VoiceClient
public VoiceClient(HttpWrapper httpWrapper)
Constructor.- Parameters:
httpWrapper- (required) shared HTTP wrapper object used for making REST calls.
-
-
Method Detail
-
createCall
public CallEvent createCall(Call callRequest) throws NexmoResponseParseException, NexmoClientException
Begin a call to a phone number.- Parameters:
callRequest- Describing the call to be made.- Returns:
- A CallEvent describing the initial state of the call, containing the
uuidrequired to interact with the ongoing phone call. - Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
listCalls
public CallInfoPage listCalls() throws NexmoResponseParseException, NexmoClientException
Obtain the first page of CallInfo objects, representing the most recent calls initiated bycreateCall(Call).- Returns:
- A CallInfoPage representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
listCalls
public CallInfoPage listCalls(CallsFilter filter) throws NexmoResponseParseException, NexmoClientException
Obtain the first page of CallInfo objects matching the query described byfilter, representing the most recent calls initiated bycreateCall(Call).- Parameters:
filter- (optional) A filter describing which calls to be listed.- Returns:
- A CallInfoPage representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
getCallDetails
public CallInfo getCallDetails(java.lang.String uuid) throws NexmoResponseParseException, NexmoClientException
Look up the status of a single call initiated bycreateCall(Call).- Parameters:
uuid- (required) The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()- Returns:
- A CallInfo object, representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
sendDtmf
public DtmfResponse sendDtmf(java.lang.String uuid, java.lang.String digits) throws NexmoResponseParseException, NexmoClientException
Send DTMF codes to an ongoing call.- Parameters:
uuid- (required) The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()digits- (required) A string specifying the digits to be sent to the call. Valid characters are the digits1-9</tt>, <tt>#</tt>, <tt>*</tt>, with the special character <tt>pindicating a short pause between tones.- Returns:
- A CallInfo object, representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
modifyCall
public ModifyCallResponse modifyCall(java.lang.String uuid, ModifyCallAction action) throws NexmoResponseParseException, NexmoClientException
Modify an ongoing call.This method modifies an ongoing call, identified by "uuid". Modifications to the call can be one of:
- Terminate the call (hangup)
- Mute a call leg (mute)
- Unmute a call leg (unmute)
- Earmuff a call leg (earmuff)
- Unearmuff a call leg (unearmuff)
- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()action- One of: "hangup", "mute", "unmute", "earmuff", "unearmuff"- Returns:
- A ModifyCallResponse object, representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
modifyCall
public ModifyCallResponse modifyCall(CallModifier modifier) throws NexmoResponseParseException, NexmoClientException
Modify an ongoing call using a CallModifier object.In most cases, you will want to use
modifyCall(String, ModifyCallAction)ortransferCall(String, String)instead of this method.- Parameters:
modifier- A CallModifier describing the modification to be made.- Returns:
- A ModifyCallResponse object, representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
transferCall
public ModifyCallResponse transferCall(java.lang.String uuid, java.lang.String nccoUrl) throws NexmoResponseParseException, NexmoClientException
Transfer a call to a different NCCO endpoint.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()nccoUrl- The URL of the NCCO endpoint the call should be transferred to- Returns:
- A ModifyCallResponse object, representing the response from the Nexmo Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startStream
public StreamResponse startStream(java.lang.String uuid, java.lang.String streamUrl, int loop) throws NexmoResponseParseException, NexmoClientException
Stream audio to an ongoing call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()streamUrl- A URL of an audio file in MP3 or 16-bit WAV format, to be streamed to the call.loop- The number of times to repeat the audio. The default value is1, or you can use0to indicate that the audio should be repeated indefinitely.- Returns:
- The data returned from the Voice API
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startStream
public StreamResponse startStream(java.lang.String uuid, java.lang.String streamUrl) throws NexmoResponseParseException, NexmoClientException
Stream audio to an ongoing call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()streamUrl- A URL of an audio file in MP3 or 16-bit WAV format, to be streamed to the call.- Returns:
- The data returned from the Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
stopStream
public StreamResponse stopStream(java.lang.String uuid) throws NexmoResponseParseException, NexmoClientException
Stop the audio being streamed into a call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()- Returns:
- The data returned from the Voice API
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startTalk
public TalkResponse startTalk(java.lang.String uuid, java.lang.String text) throws NexmoResponseParseException, NexmoClientException
Send a synthesized speech message to an ongoing call.The message will only play once, spoken with the default voice of Kimberly.
- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()text- The message to be spoken to the call participants.- Returns:
- The data returned from the Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startTalk
public TalkResponse startTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName) throws NexmoResponseParseException, NexmoClientException
Send a synthesized speech message to an ongoing call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()text- The message to be spoken to the call participants.voiceName- The voice to be used to speak the message.- Returns:
- The data returned from the Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startTalk
public TalkResponse startTalk(java.lang.String uuid, java.lang.String text, int loop) throws NexmoResponseParseException, NexmoClientException
Send a synthesized speech message to an ongoing call.The message will be spoken with the default voice of Kimberly.
- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()text- The message to be spoken to the call participants.loop- The number of times to repeat the message. The default value is1, or you can use0to indicate that the message should be repeated indefinitely.- Returns:
- The data returned from the Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
startTalk
public TalkResponse startTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName, int loop) throws NexmoResponseParseException, NexmoClientException
Send a synthesized speech message to an ongoing call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()text- The message to be spoken to the call participants.voiceName- The voice to be used to speak the message.loop- The number of times to repeat the message. The default value is1, or you can use0to indicate that the message should be repeated indefinitely.- Returns:
- The data returned from the Voice API.
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
stopTalk
public TalkResponse stopTalk(java.lang.String uuid) throws NexmoResponseParseException, NexmoClientException
Stop the message being spoken into a call.- Parameters:
uuid- The UUID of the call, obtained from the object returned bycreateCall(Call). This value can be obtained withCallEvent.getUuid()- Returns:
- The data returned from the Voice API
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
downloadRecording
public Recording downloadRecording(java.lang.String recordingUrl) throws NexmoResponseParseException, NexmoClientException
Download a recording, given the recordingUrl provided from the webhook callback.This returns a
Recordingobject which can provide an InputStream of the byte data, or can be used to save directly to file.- Parameters:
recordingUrl- The recordingUrl provided by the webhook callback- Returns:
- A Recording object, providing access to the recording's bytes
- Throws:
NexmoClientException- if there was a problem with the Nexmo request or response objects.NexmoResponseParseException- if the response from the API could not be parsed.
-
-