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 and Description
protected CallsEndpoint	calls
protected DtmfEndpoint	dtmf
protected StreamsEndpoint	streams
protected TalkEndpoint	talk

Fields inherited from class com.nexmo.client.AbstractClient

httpWrapper

Constructor Summary

Constructors

Constructor and Description
VoiceClient(HttpWrapper httpWrapper) Constructor.

Method Summary

Modifier and Type	Method and Description
CallEvent	createCall(Call callRequest) Begin a call to a phone number.
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(java.lang.String uuid, java.lang.String action) Hang up a 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.

Methods inherited from class java.lang.Object

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

Field Detail

calls

protected final CallsEndpoint calls

streams

protected final StreamsEndpoint streams

talk

protected final TalkEndpoint talk

dtmf

protected final DtmfEndpoint dtmf

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 java.io.IOException,
                            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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

listCalls

public CallInfoPage listCalls()
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

listCalls

public CallInfoPage listCalls(CallsFilter filter)
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

getCallDetails

public CallInfo getCallDetails(java.lang.String uuid)
                        throws java.io.IOException,
                               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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

sendDtmf

public DtmfResponse sendDtmf(java.lang.String uuid,
                             java.lang.String digits)
                      throws java.io.IOException,
                             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, #, *, with the special character p indicating a short pause between tones.

Returns:

A CallInfo object, representing the response from the Nexmo Voice API.

Throws:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

modifyCall

public ModifyCallResponse modifyCall(java.lang.String uuid,
                                     java.lang.String action)
                              throws java.io.IOException,
                                     NexmoClientException

Hang up a call.

In future, further operations will be possible. At the moment, the only valid value for action is hangup.

Parameters:

uuid - (required) The UUID of the call, obtained from the object returned by createCall(Call). This value can be obtained with CallEvent.getUuid()

action - The word "hangup"

Returns:

A CallInfo object, representing the response from the Nexmo Voice API.

Throws:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startStream

public StreamResponse startStream(java.lang.String uuid,
                                  java.lang.String streamUrl,
                                  int loop)
                           throws java.io.IOException,
                                  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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startStream

public StreamResponse startStream(java.lang.String uuid,
                                  java.lang.String streamUrl)
                           throws java.io.IOException,
                                  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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

stopStream

public StreamResponse stopStream(java.lang.String uuid)
                          throws java.io.IOException,
                                 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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startTalk

public TalkResponse startTalk(java.lang.String uuid,
                              java.lang.String text)
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startTalk

public TalkResponse startTalk(java.lang.String uuid,
                              java.lang.String text,
                              VoiceName voiceName)
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startTalk

public TalkResponse startTalk(java.lang.String uuid,
                              java.lang.String text,
                              int loop)
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

startTalk

public TalkResponse startTalk(java.lang.String uuid,
                              java.lang.String text,
                              VoiceName voiceName,
                              int loop)
                       throws java.io.IOException,
                              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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.

stopTalk

public TalkResponse stopTalk(java.lang.String uuid)
                      throws java.io.IOException,
                             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:

java.io.IOException - if a network error occurred contacting the Nexmo Voice API.

NexmoClientException - if there was a problem with the Nexmo request or response objects.