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 use NexmoClient.getVoiceClient().

Field Summary

Fields

Modifier and Type	Field	Description
protected com.nexmo.client.voice.CallsEndpoint	calls
protected com.nexmo.client.voice.DownloadRecordingEndpoint	downloadRecording
protected DtmfEndpoint	dtmf
protected com.nexmo.client.voice.StreamsEndpoint	streams
protected TalkEndpoint	talk

Fields inherited from class com.nexmo.client.AbstractClient

httpWrapper

Constructor Summary

Constructors

Constructor	Description
VoiceClient(HttpWrapper httpWrapper)	Constructor.

Method Summary

Modifier and Type	Method	Description
CallEvent	createCall(Call callRequest)	Begin a call to a phone number.
Recording	downloadRecording(java.lang.String recordingUrl)	Download a recording, given the recordingUrl provided from the webhook callback.
CallInfo	getCallDetails(java.lang.String uuid)	Look up the status of a single call initiated by createCall(Call).
CallInfoPage	listCalls()	Obtain the first page of CallInfo objects, representing the most recent calls initiated by createCall(Call).
CallInfoPage	listCalls(CallsFilter filter)	Obtain the first page of CallInfo objects matching the query described by filter, representing the most recent calls initiated by createCall(Call).
ModifyCallResponse	modifyCall(CallModifier modifier)	Modify an ongoing call using a CallModifier object.
ModifyCallResponse	modifyCall(java.lang.String uuid, ModifyCallAction action)	Modify an ongoing call.
DtmfResponse	sendDtmf(java.lang.String uuid, java.lang.String digits)	Send DTMF codes to an ongoing call.
StreamResponse	startStream(java.lang.String uuid, java.lang.String streamUrl)	Stream audio to an ongoing call.
StreamResponse	startStream(java.lang.String uuid, java.lang.String streamUrl, int loop)	Stream audio to an ongoing call.
TalkResponse	startTalk(java.lang.String uuid, java.lang.String text)	Send a synthesized speech message to an ongoing call.
TalkResponse	startTalk(java.lang.String uuid, java.lang.String text, int loop)	Send a synthesized speech message to an ongoing call.
TalkResponse	startTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName)	Send a synthesized speech message to an ongoing call.
TalkResponse	startTalk(java.lang.String uuid, java.lang.String text, VoiceName voiceName, int loop)	Send a synthesized speech message to an ongoing call.
StreamResponse	stopStream(java.lang.String uuid)	Stop the audio being streamed into a call.
TalkResponse	stopTalk(java.lang.String uuid)	Stop the message being spoken into a call.
ModifyCallResponse	transferCall(java.lang.String uuid, java.lang.String nccoUrl)	Transfer a call to a different NCCO endpoint.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 uuid required 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 by createCall(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 by filter, representing the most recent calls initiated by createCall(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 by createCall(Call).

Parameters:

uuid - (required) The UUID of the call, obtained from the object returned by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.getUuid()

digits - (required) A string specifying the digits to be sent to the call. Valid characters are the digits 1-9</tt>, <tt>#</tt>, <tt>*</tt>, with the special character <tt>p indicating 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 by createCall(Call). This value can be obtained with CallEvent.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) or transferCall(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 by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.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 is 1, or you can use 0 to 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 by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.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 by createCall(Call). This value can be obtained with CallEvent.getUuid()

text - The message to be spoken to the call participants.

loop - The number of times to repeat the message. The default value is 1, or you can use 0 to 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 by createCall(Call). This value can be obtained with CallEvent.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 is 1, or you can use 0 to 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 by createCall(Call). This value can be obtained with CallEvent.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 Recording object 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.