Package com.vonage.client.conversations

Class ConversationsClient

java.lang.Object

com.vonage.client.conversations.ConversationsClient

public class ConversationsClient
extends Object

A client for communicating with the Vonage Conversations API. The standard way to obtain an instance of this class is to use VonageClient.getConversationsClient().

Constructor Summary

Constructors

Constructor	Description
ConversationsClient(HttpWrapper wrapper)	Constructor.

Method Summary

Modifier and Type	Method	Description
Conversation	createConversation(Conversation request)	Creates a new Conversation within the application.
<E extends Event> E	createEvent(String conversationId, E request)	Creates a new Event for the specified conversation.
Member	createMember(String conversationId, Member request)	Creates a new Member for the specified conversation.
void	deleteConversation(String conversationId)	Delete an existing conversation by ID.
void	deleteEvent(String conversationId, int eventId)	Deletes an event.
Conversation	getConversation(String conversationId)	Retrieve a conversation by its ID.
Event	getEvent(String conversationId, int eventId)	Retrieve a conversation Event by its ID.
Member	getMember(String conversationId, String memberId)	Retrieve a conversation Member by its ID.
List<BaseConversation>	listConversations()	Retrieve the first 100 Conversations in the application.
ListConversationsResponse	listConversations(ListConversationsRequest filter)	Retrieve conversations in the application which match the specified filter criteria.
List<Event>	listEvents(String conversationId)	List the first 100 events for a given Conversation.
ListEventsResponse	listEvents(String conversationId, ListEventsRequest request)	Retrieve Events associated with a particular Conversation which match the specified filter criteria.
List<BaseMember>	listMembers(String conversationId)	List the first 100 Members for a given Conversation.
ListMembersResponse	listMembers(String conversationId, ListMembersRequest filter)	Retrieve Members associated with a particular Conversation which match the specified filter criteria.
List<UserConversation>	listUserConversations(String userId)	List the first 100 conversations for a given user.
ListUserConversationsResponse	listUserConversations(String userId, ListUserConversationsRequest filter)	List the first 100 conversations for a given user.
Conversation	updateConversation(String conversationId, Conversation request)	Update an existing conversation's settings / parameters.
Member	updateMember(UpdateMemberRequest request)	Update an existing member's state.

Methods inherited from class java.lang.Object

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

Constructor Details

ConversationsClient

public ConversationsClient(HttpWrapper wrapper)

Constructor.

Parameters:

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

Method Details

listConversations

public List<BaseConversation> listConversations()

Retrieve the first 100 Conversations in the application. Note that the returned conversations are incomplete, hence of type BaseConversation. To get the full data, use the getConversation(String) method, passing in the ID from BaseConversation.getId().

Returns:

A list of the first 100 conversations returned from the API, in default (ascending) order.

Throws:

ConversationsResponseException - If the API call fails due to a bad request (400).

See Also:

• listConversations(ListConversationsRequest)

listConversations

public ListConversationsResponse listConversations(ListConversationsRequest filter)

Retrieve conversations in the application which match the specified filter criteria. Note that the returned conversations in ListConversationsResponse.getConversations() are incomplete, hence type of BaseConversation. To get the full data, use getConversation(String) method, passing in the ID from BaseConversation.getId().

Parameters:

filter - Filter options to narrow down the search results.

Returns:

The search results along with HAL metadata.

Throws:

ConversationsResponseException - If the API call fails due to a bad request (400).

createConversation

public Conversation createConversation(Conversation request)

Creates a new Conversation within the application.

Parameters:

request - The Conversation parameters. Use Conversation.builder().build() for default settings.

Returns:

The created Conversation response with additional fields populated.

Throws:

ConversationsResponseException - If the Conversation name already exists (409), or any other API error.

getConversation

public Conversation getConversation(String conversationId)

Retrieve a conversation by its ID.

Parameters:

conversationId - Unique identifier of the conversation to look up.

Returns:

Details of the conversation corresponding to the specified ID.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

updateConversation

public Conversation updateConversation(String conversationId,
 Conversation request)

Update an existing conversation's settings / parameters.

Parameters:

conversationId - Unique conversation identifier.

request - Conversation object with the updated parameters. Any fields not set will be unchanged.

Returns:

The full updated conversation details.

Throws:

ConversationsResponseException - If the conversation was not found (404) or the parameters are invalid (400), e.g. the updated name already exists (409).

deleteConversation

public void deleteConversation(String conversationId)

Delete an existing conversation by ID.

Parameters:

conversationId - Unique conversation identifier.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

listUserConversations

public List<UserConversation> listUserConversations(String userId)

List the first 100 conversations for a given user.

Parameters:

userId - Unique identifier for the user.

Returns:

The list of conversations the specified user is in, with default (ascending) order.

Throws:

ConversationsResponseException - If the user was not found (404), or any other API error.

See Also:

• listUserConversations(String, ListUserConversationsRequest)
• com.vonage.client.users

listUserConversations

public ListUserConversationsResponse listUserConversations(String userId,
 ListUserConversationsRequest filter)

List the first 100 conversations for a given user.

Parameters:

userId - Unique identifier for the user.

filter - Filter options to narrow down the search results.

Returns:

The wrapped list of user conversations, along with HAL metadata.

Throws:

ConversationsResponseException - If the user was not found (404), the filter options were invalid (400) or any other API error.

See Also:

• com.vonage.client.users

listMembers

public List<BaseMember> listMembers(String conversationId)

List the first 100 Members for a given Conversation. Note that the returned members are incomplete, hence of type BaseMember. To get the full data, use the getMember(String, String) method, passing in the ID from BaseMember.getId().

Parameters:

conversationId - Unique conversation identifier.

Returns:

The list of members in default (ascending) order.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

See Also:

• listMembers(String, ListMembersRequest)

listMembers

public ListMembersResponse listMembers(String conversationId,
 ListMembersRequest filter)

Retrieve Members associated with a particular Conversation which match the specified filter criteria. Note that the returned members are incomplete, hence of type BaseMember. To get the full data, use the getMember(String, String) method, passing in the ID from BaseMember.getId().

Parameters:

conversationId - Unique conversation identifier.

filter - Filter options to narrow down the search results.

Returns:

The wrapped list of Members, along with HAL metadata.

Throws:

ConversationsResponseException - If the conversation was not found (404), the filter options were invalid (400) or any other API error.

getMember

public Member getMember(String conversationId,
 String memberId)

Retrieve a conversation Member by its ID.

Parameters:

conversationId - Unique conversation identifier.

memberId - Unique identifier for the member.

Returns:

Details of the member corresponding to the specified ID.

Throws:

ConversationsResponseException - If the conversation or member was not found (404), or any other API error.

createMember

public Member createMember(String conversationId,
 Member request)

Creates a new Member for the specified conversation.

Parameters:

conversationId - Unique conversation identifier.

request - The Members parameters. Use Member.builder(), remember to set the mandatory parameters.

Returns:

The created Member response with additional fields populated.

Throws:

ConversationsResponseException - If the conversation was not found (404), the request parameters were invalid (400) or any other API error.

updateMember

public Member updateMember(UpdateMemberRequest request)

Update an existing member's state.

Parameters:

request - Details of the member to update. Use UpdateMemberRequest.builder(), remember to set the mandatory parameters, including the conversation and member IDs.

Returns:

The updated Member object response.

Throws:

ConversationsResponseException - If the conversation or member were not found (404), the request parameters were invalid (400) or any other API error.

listEvents

public List<Event> listEvents(String conversationId)

List the first 100 events for a given Conversation.

Parameters:

conversationId - Unique conversation identifier.

Returns:

The list of events in default (ascending) order.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

listEvents

public ListEventsResponse listEvents(String conversationId,
 ListEventsRequest request)

Retrieve Events associated with a particular Conversation which match the specified filter criteria.

Parameters:

conversationId - Unique conversation identifier.

request - Filter options to narrow down the search results.

Returns:

The wrapped list of Events, along with HAL metadata.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

getEvent

public Event getEvent(String conversationId,
 int eventId)

Retrieve a conversation Event by its ID.

Parameters:

conversationId - Unique conversation identifier.

eventId - Sequence ID of the event to retrieve as an integer.

Returns:

Details of the event corresponding to the specified ID.

Throws:

ConversationsResponseException - If the conversation or event was not found (404), or any other API error.

createEvent

public <E extends Event> E createEvent(String conversationId,
 E request)

Creates a new Event for the specified conversation.

Parameters:

conversationId - Unique conversation identifier.

request - Details of the event to create.

Returns:

The created Event response with additional fields populated.

Throws:

ConversationsResponseException - If the conversation was not found (404), or any other API error.

deleteEvent

public void deleteEvent(String conversationId,
 int eventId)

Deletes an event. Only message and custom events can be deleted.

Parameters:

conversationId - Unique conversation identifier.

eventId - Sequence ID of the event to retrieve as an integer.

Throws:

ConversationsResponseException - If the conversation or event was not found (404), the event could not be deleted, or any other API error.