Package com.vonage.client.voice

Class VoiceClient

java.lang.Object

com.vonage.client.voice.VoiceClient

public class VoiceClient
extends Object

A client for talking to the Vonage Voice API. The standard way to obtain an instance of this class is to use VonageClient.getVoiceClient().

Constructor Summary

Constructors

Constructor	Description
VoiceClient(HttpWrapper wrapper)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	addDtmfListener(String uuid, String eventUrl)	Register a listener for asynchronous DTMF events sent by a caller to an InputAction NCCO action, when the InputAction.Builder.mode(InputMode) is InputMode.ASYNCHRONOUS.
CallEvent	createCall(Call callRequest)	Begin a call to a phone number.
byte[]	downloadRecordingRaw(String recordingUrl)	Download a recording.
void	earmuffCall(String callId)	Modify a call with the ModifyCallAction.EARMUFF action.
CallInfo	getCallDetails(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).
void	muteCall(String callId)	Modify a call with the ModifyCallAction.MUTE action.
void	removeDtmfListener(String uuid)	Stop receiving updates for asynchronous DTMF events sent by a caller to an InputAction NCCO, when the InputAction.Builder.mode(InputMode) is InputMode.ASYNCHRONOUS.
void	saveRecording(String recordingUrl, Path destination)	Download a recording and save it to a file.
DtmfResponse	sendDtmf(String uuid, String digits)	Send DTMF codes to an ongoing call.
StreamResponse	startStream(String uuid, String streamUrl)	Stream audio to an ongoing call.
StreamResponse	startStream(String uuid, String streamUrl, int loop)	Stream audio to an ongoing call.
StreamResponse	startStream(String uuid, String streamUrl, int loop, double level)	Stream audio to an ongoing call.
TalkResponse	startTalk(String uuid, TalkPayload properties)	Send a synthesized speech message to an ongoing call.
TalkResponse	startTalk(String uuid, String text)	Deprecated. Use startTalk(String, TalkPayload).
TalkResponse	startTalk(String uuid, String text, int loop)	Deprecated. Use startTalk(String, TalkPayload).
TalkResponse	startTalk(String uuid, String text, TextToSpeechLanguage language)	Deprecated. Use startTalk(String, TalkPayload).
TalkResponse	startTalk(String uuid, String text, TextToSpeechLanguage language, int style)	Deprecated. Use startTalk(String, TalkPayload).
TalkResponse	startTalk(String uuid, String text, TextToSpeechLanguage language, int style, int loop)	Deprecated. Use startTalk(String, TalkPayload).
StreamResponse	stopStream(String uuid)	Stop the audio being streamed into a call.
TalkResponse	stopTalk(String uuid)	Stop the message being spoken into a call.
void	terminateCall(String callId)	Modify a call with the ModifyCallAction.HANGUP action.
void	transferCall(String uuid, Ncco ncco)	Transfer a call to a different NCCO.
void	transferCall(String uuid, String nccoUrl)	Transfer a call to a different NCCO endpoint.
void	unearmuffCall(String callId)	Modify a call with the ModifyCallAction.UNEARMUFF action.
void	unmuteCall(String callId)	Modify a call with the ModifyCallAction.UNMUTE action.
static boolean	verifySignature(String jwt, String secret)	Utility method for verifying whether a token was signed by a secret.

Methods inherited from class java.lang.Object

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

Constructor Details

VoiceClient

public VoiceClient(HttpWrapper wrapper)

Constructor.

Parameters:

wrapper - (required) shared HTTP wrapper object used for making REST calls.

Method Details

createCall

public CallEvent createCall(Call callRequest)
                     throws VonageResponseParseException,
VonageClientException

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

listCalls

public CallInfoPage listCalls()
                       throws VonageResponseParseException,
VonageClientException

Obtain the first page of CallInfo objects, representing the most recent calls initiated by createCall(Call).

Returns:

A CallInfoPage representing the response from the Vonage Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

listCalls

public CallInfoPage listCalls(CallsFilter filter)
                       throws VonageResponseParseException,
VonageClientException

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 Vonage Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

getCallDetails

public CallInfo getCallDetails(String uuid)
                        throws VonageResponseParseException,
VonageClientException

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 Vonage Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

sendDtmf

public DtmfResponse sendDtmf(String uuid,
 String digits)
                      throws VonageResponseParseException,
VonageClientException

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 Vonage Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

earmuffCall

public void earmuffCall(String callId)
                 throws VoiceResponseException

Modify a call with the ModifyCallAction.EARMUFF action. This prevents the call from hearing audio.

Parameters:

callId - UUID of the call.

Throws:

VoiceResponseException - If there was an error performing the action.

Since:

7.11.0

unearmuffCall

public void unearmuffCall(String callId)
                   throws VoiceResponseException

Modify a call with the ModifyCallAction.UNEARMUFF action. This allows the call to hear audio again.

Parameters:

callId - UUID of the call.

Throws:

VoiceResponseException - If there was an error performing the action.

Since:

7.11.0

muteCall

public void muteCall(String callId)
              throws VoiceResponseException

Modify a call with the ModifyCallAction.MUTE action.

Parameters:

callId - UUID of the call.

Throws:

VoiceResponseException - If there was an error performing the action.

Since:

7.11.0

unmuteCall

public void unmuteCall(String callId)
                throws VoiceResponseException

Modify a call with the ModifyCallAction.UNMUTE action.

Parameters:

callId - UUID of the call.

Throws:

VoiceResponseException - If there was an error performing the action.

Since:

7.11.0

terminateCall

public void terminateCall(String callId)
                   throws VoiceResponseException

Modify a call with the ModifyCallAction.HANGUP action.

Parameters:

callId - UUID of the call.

Throws:

VoiceResponseException - If there was an error performing the action.

Since:

7.11.0

transferCall

public void transferCall(String uuid,
 String nccoUrl)
                  throws VonageResponseParseException,
VonageClientException

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.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

transferCall

public void transferCall(String uuid,
 Ncco ncco)
                  throws VonageResponseParseException,
VonageClientException

Transfer a call to a different NCCO.

Parameters:

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

ncco - The new NCCO that will be used in the call.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startStream

public StreamResponse startStream(String uuid,
 String streamUrl,
 int loop)
                           throws VonageResponseParseException,
VonageClientException

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startStream

public StreamResponse startStream(String uuid,
 String streamUrl,
 int loop,
 double level)
                           throws VonageResponseParseException,
VonageClientException

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.

level - The audio level of the stream, between -1 and 1 with a precision of 0.1. The default value is 0.

Returns:

The data returned from the Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

Since:

7.3.0

startStream

public StreamResponse startStream(String uuid,
 String streamUrl)
                           throws VonageResponseParseException,
VonageClientException

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

stopStream

public StreamResponse stopStream(String uuid)
                          throws VonageResponseParseException,
VonageClientException

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startTalk

public TalkResponse startTalk(String uuid,
 TalkPayload properties)

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().

properties - Properties of the text-to-speech request.

Returns:

Metadata from the Voice API if successful.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

Since:

7.3.0

startTalk

@Deprecated
public TalkResponse startTalk(String uuid,
 String text)
                       throws VonageResponseParseException,
VonageClientException

Deprecated.

Use startTalk(String, TalkPayload).

Send a synthesized speech message to an ongoing call.

The message will only play once, spoken with the default en-US voice.

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startTalk

@Deprecated
public TalkResponse startTalk(String uuid,
 String text,
 TextToSpeechLanguage language)
                       throws VonageResponseParseException,
VonageClientException

Deprecated.

Use startTalk(String, TalkPayload).

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.

language - The Language to use when converting text-to-speech.

Returns:

The data returned from the Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startTalk

@Deprecated
public TalkResponse startTalk(String uuid,
 String text,
 int loop)
                       throws VonageResponseParseException,
VonageClientException

Deprecated.

Use startTalk(String, TalkPayload).

Send a synthesized speech message to an ongoing call.

The message will be spoken with the default en-US voice.

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startTalk

@Deprecated
public TalkResponse startTalk(String uuid,
 String text,
 TextToSpeechLanguage language,
 int style,
 int loop)
                       throws VonageResponseParseException,
VonageClientException

Deprecated.

Use startTalk(String, TalkPayload).

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.

language - The language to use for the text-to-speech.

style - The language style to use for the text-to-speech.

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

startTalk

@Deprecated
public TalkResponse startTalk(String uuid,
 String text,
 TextToSpeechLanguage language,
 int style)
                       throws VonageResponseParseException,
VonageClientException

Deprecated.

Use startTalk(String, TalkPayload).

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.

language - The language to use for the text-to-speech.

style - The language style to use for the text-to-speech.

Returns:

The data returned from the Voice API.

Throws:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

stopTalk

public TalkResponse stopTalk(String uuid)
                      throws VonageResponseParseException,
VonageClientException

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:

VonageClientException - if there was a problem with the Vonage request or response objects.

VonageResponseParseException - if the response from the API could not be parsed.

addDtmfListener

public void addDtmfListener(String uuid,
 String eventUrl)
                     throws VoiceResponseException

Register a listener for asynchronous DTMF events sent by a caller to an InputAction NCCO action, when the InputAction.Builder.mode(InputMode) is InputMode.ASYNCHRONOUS.

Parameters:

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

eventUrl - The URL to send asynchronous DTMF user input events to.

Throws:

VoiceResponseException - If the call does not exist or the listener could not be added, for example if the call's state or input mode are incompatible.

Since:

8.12.0

removeDtmfListener

public void removeDtmfListener(String uuid)
                        throws VoiceResponseException

Stop receiving updates for asynchronous DTMF events sent by a caller to an InputAction NCCO, when the InputAction.Builder.mode(InputMode) is InputMode.ASYNCHRONOUS. Calling this method stops sending DTMF events to the event URL set in addDtmfListener(String, String).

Parameters:

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

Throws:

VoiceResponseException - If the call does not exist or have a listener attached.

Since:

8.12.0

downloadRecordingRaw

public byte[] downloadRecordingRaw(String recordingUrl)

Download a recording.

Parameters:

recordingUrl - The recording URL, as obtained from the webhook callback.

Returns:

The raw contents of the downloaded recording as a byte array.

Throws:

IllegalArgumentException - If the recordingUrl is invalid.

VoiceResponseException - If there was an error downloading the recording from the URL.

Since:

7.11.0

saveRecording

public void saveRecording(String recordingUrl,
 Path destination)
                   throws IOException

Download a recording and save it to a file.

Parameters:

recordingUrl - The recording URL, as obtained from the webhook callback.

destination - Path to save the recording to.

Throws:

IOException - If there was an error writing to the file.

VoiceResponseException - If there was an error downloading the recording from the URL.

IllegalArgumentException - If the recordingUrl is invalid.

Since:

7.11.0

verifySignature

public static boolean verifySignature(String jwt,
 String secret)

Utility method for verifying whether a token was signed by a secret. This is mostly useful when using signed callbacks to ensure that the inbound data came from Vonage servers. The signature is performed using the SHA-256 HMAC algorithm.

Parameters:

jwt - The JSON Web Token to verify.

secret - The symmetric secret key (HS256) to use for decrypting the token's signature.

Returns:

true if the token was signed by the secret, false otherwise.

Since:

7.11.0