API reference for the Android SDK - Intelligent Media Services

The Android SDK provides APIs for managing chat sessions, sending messages, handling voice interactions, and uploading attachments.

API overview

Class/Protocol	API	Description
*ARTCAIChatEngine* The conversation engine interface.	setEngineCallback	Registers a callback for the conversation engine.
	destory	Releases resources.
	setTemplateConfig	Configures conversation parameters. Optional.
	setUserData	Sets custom user information, which is passed to the agent as a custom extension field.
	startChat	Starts a chat.
	endChat	Ends a chat.
	sendMessage	Sends a text message.
	startPushVoiceMessage	Starts push-to-talk voice messaging.
	finishPushVoiceMessage	Ends push-to-talk voice messaging.
	cancelPushVoiceMessage	Cancels push-to-talk voice messaging.
	interruptAgentResponse	Interrupts the agent's output.
	deleteMessage	Deletes a message.
	queryMessageList	Queries historical messages.
	getAgentInfo	Retrieves agent information.
	startPlayMessage	Starts text-to-speech playback for a message.
	stopPlayMessage	Stops text-to-speech playback.
	isPlayingMessage	Checks whether text-to-speech playback is in progress.
	getVoiceList	Retrieves the list of available text-to-speech voices.
	getCurrentVoice	Retrieves the current text-to-speech voice.
	getCurrentAIChatAgentState	Retrieves the current response state of the agent.
	createAttachmentUploader	Creates an attachment uploader. Attachments can be images or files.
	getEngineState	Retrieves the current state of the engine.
	parseShareConfig	Parses the information of a shared agent.
	generateShareAgentChat	Starts a conversation with a shared agent.
*IARTCAIChatEngineCallback* Callback events for the conversation engine.	onRequestAuthToken	Requests an authentication token. This is a required callback.
	onEngineStateChange	Triggered when the engine state changes.
	onReceivedMessage	Triggered when a message is received.
	onUserMessageUpdated	Triggered when fields in a message sent by the user are updated.
	onAgentResponseStateChange	Triggered when the agent's response state changes.
	onMessagePlayStateChange	Triggered when the text-to-speech playback state changes.
	onErrorOccurs	Triggered when an error occurs.
	onReceivedCustomMessage	Triggered when a custom message is received.
*ARTCAIChatAttachmentUploader* The attachment uploader.	registerAttachmentUploadCallback	Registers an upload callback for attachments.
	addAttachment	Adds an attachment object.
	removeAttachment	Removes an attachment object.
	getAttachmentList	Retrieves the list of attachments.
	allUploadSussess	Checks whether all attachments are successfully uploaded.
*IARTCAIChatAttachmentUploadCallback* Callbacks for attachment upload progress.	onSuccess	Triggered when the upload is successful.
	onFailure	Triggered when the upload fails.
	onProgress	Reports the upload progress.

API details

ARTCAIChatEngine details

setEngineCallback

Registers a callback.

/**
* Registers a callback.
* @param engineCallback
*/
public abstract void setEngineCallback(ARTCAIChatEngine.IARTCAIChatEngineCallback engineCallback);

Parameters:

Parameter	Type	Description
engineCallback	IARTCAIChatEngineCallback	The engine callback.

destory

Releases resources.

 /**
* Releases resources.
*/
public abstract void destory();

setTemplateConfig

Configures conversation parameters. You can skip this operation if no business parameters are needed.

public abstract void setTemplateConfig(ARTCAIChatTemplateConfig templateConfig);

Parameters:

Parameter	Type	Description
templateConfig	ARTCAIChatTemplateConfig	The TemplateConfig parameters for the conversation.

setUserData

Sets custom user information, which is passed to the agent as a custom extension field.

public abstract void setUserData(String userData);

Parameters:

Parameter	Type	Description
userData	String	The custom user information.

startChat

Starts a chat.

/**
     * Starts a chat.
     * @param userInfo
     * @param agentInfo
     * @param sessionId The unique ID of the current session. If this parameter is left empty, the unique ID is a combination of the user ID and the agent ID.
     */
    public abstract void startChat(ARTCAIChatUserInfo userInfo, ARTCAIChatAgentInfo agentInfo, String sessionId);

Parameters:

Parameter	Type	Description
userInfo	ARTCAIChatUserInfo	The user information. The user ID is required and can be your business user ID.
agentInfo	ARTCAIChatAgentInfo	The agent information. The agent ID is required.
sessionId	String	The unique session ID. If left empty, defaults to a combination of the user ID and agent ID. Used to associate all chat records between the user and the agent.

endChat

Ends a chat.

    /**
     * Ends a chat.
     * @param needLogout
     */
    public abstract void endChat(boolean needLogout);

Parameters:

Parameter	Type	Description
needLogout	boolean	Specifies whether to end the chat and log out from the Instant Messaging (IM) service.

sendMessage

Sends a text message.

 /**
 * Sends a text message.
 * @param request
 */
public abstract void sendMessage(ARTCAIChatSendMessageRequest request, IARTCAIChatMessageCallback callback);

Parameters:

Parameter	Type	Description
request	ARTCAIChatSendMessageRequest	The request to send a message.
callback	IARTCAIChatMessageCallback	The callback for sending the text message.

startPushVoiceMessage

Starts push-to-talk voice messaging.

/**
* Starts push-to-talk.
* @param request
*/
public abstract boolean startPushVoiceMessage(ARTCAIChatSendMessageRequest request);

Parameters:

Parameter	Type	Description
request	ARTCAIChatSendMessageRequest	The request to send a message.

finishPushVoiceMessage

Ends push-to-talk voice messaging.

    /**
     * Ends push-to-talk.
     * @param callback
     */
    public abstract void finishPushVoiceMessage( IARTCAIChatMessageCallback callback);

Parameters:

Parameter	Type	Description
request	IARTCAIChatMessageCallback	The callback for sending the push-to-talk voice message.

cancelPushVoiceMessage

Cancels push-to-talk voice messaging.

    /**
     * Cancels push-to-talk.
     */
    public abstract void cancelPushVoiceMessage();

interruptAgentResponse

Interrupts the agent's output.

    /**
     * Interrupts the agent's output.
     */
    public abstract void interruptAgentResponse();

deleteMessage

Deletes a message.

    /**
     * Deletes a message.
     * @param message
     */
    public abstract void deleteMessage(ARTCAIChatMessage message, IARTCAIChatMessageCallback callback);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessage	The message record to delete.
callback	IARTCAIChatMessageCallback	The callback for deleting the message.

queryMessageList

Queries historical messages.

 /**
  * Queries the list of historical messages.
  * @param request The request model.
  * @param callback
  */
public abstract void queryMessageList(ARTCAIChatMessageListRequest request, IARTCAIChatHistoryMessageCallback callback);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessageListRequest	The request for querying historical messages.
callback	IARTCAIChatHistoryMessageCallback	The callback for querying historical messages.

getAgentInfo

Retrieves agent information.

/**
 * Gets agent information.
 */
public abstract ARTCAIChatAgentInfo  getAgentInfo();

startPlayMessage

Starts text-to-speech playback for a message.

/**
 * Starts text-to-speech playback.
 * @param message The message for playback.
 * @param voiceId The voice for playback.
 * @param callback The callback message.
 */
 public abstract void startPlayMessage(ARTCAIChatMessage message, String voiceId, IARTCAIChatMessageCallback callback);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessage	The message to start text-to-speech playback for.
voiceId	String	The voice for playback.
callback	IARTCAIChatMessageCallback	The callback for text-to-speech playback.

stopPlayMessage

Stops text-to-speech playback.

 /**
  * Stops the playback of the message content.
  */
public abstract void stopPlayMessage();

isPlayingMessage

Checks whether text-to-speech playback is in progress.

 /**
  * Checks whether text-to-speech playback is in progress.
  */
  public abstract boolean isPlayingMessage(String messageId);

Parameters:

Parameter	Type	Description
messageId	String	The ID of the message to check.

getVoiceList

Retrieves the list of available text-to-speech voices.

/**
 * The list of available voices.
 */
public abstract List<String> getVoiceList();

getCurrentVoice

Retrieves the current text-to-speech voice.

/**
 * The current voice.
 */
public abstract String getCurrentVoice();

getCurrentAIChatAgentState

Retrieves the current response state of the agent.


/**
 * Gets the current response state of the agent.
 */
public abstract ARTCAIChatAgentState getCurrentAIChatAgentState();

createAttachmentUploader

Creates an attachment uploader. Attachments can be images or files.

/**
  * Creates an attachment uploader object. You can create only one object.
  * @return
*/
public abstract ARTCAIChatAttachmentUploader createAttachmentUploader()

getEngineState

Retrieves the current state of the engine.


 /**
  * Gets the current state of the engine.
  */
public abstract ARTCAIChatEngineState getEngineState();

parseShareConfig

Parses the information of a shared agent.


/**
 * Parses the information of a shared agent.
 * @param shareInfo
 * @return
 */
public abstract ARTCAIChatAgentShareConfig parseShareConfig(String shareInfo);

Parameters:

Parameter	Type	Description
shareInfo	String	The shared agent information string.

generateShareAgentChat

Starts a conversation with a shared agent.

/**
 * Starts a conversation with a shared agent.
 * @param shareConfig
 * @param userId
 * @param callback
 */
 public abstract void generateShareAgentChat(ARTCAIChatAgentShareConfig shareConfig, String userId, IARTCAIChatGenerateShareAgentCallback callback);

Parameters:

Parameter	Type	Description
shareConfig	ARTCAIChatAgentShareConfig	The configuration information of the shared agent.
userId	String	The user ID.
callback	IARTCAIChatGenerateShareAgentCallback	The callback for the shared agent.

IARTCAIChatEngineCallback details

onRequestAuthToken

Requests an authentication token. This callback is required. Call the generateMessageChatToken operation on your app server or business server to obtain the token for AICall SDK authentication.

/**
 * Requests an authentication token.
 * @param userId
 * @param callback
*/
public void onRequestAuthToken(String userId, IARTCAIChatAuthTokenCallback callback);

Parameters:

Parameter	Type	Description
userId	String	The user ID.
callback	IARTCAIChatAuthTokenCallback	The callback for retrieving the token.

onEngineStateChange

Triggered when the engine state changes.

/**
 * Triggered when the engine state changes.
 *
 * @param oldState The state of the engine before the change.
 * @param newState The new state of the engine.
 */
public void onEngineStateChange(ARTCAIChatEngineState oldState, ARTCAIChatEngineState newState);

Parameters:

Parameter	Type	Description
oldState	ARTCAIChatEngineState	The state of the engine before the change.
newState	ARTCAIChatEngineState	The new state of the engine.

onReceivedMessage

Triggered when a message is received.

/**
 * Triggered when a message is received.
 * This method handles the received ARTCAIChatMessage object. You can implement the message logic here.
 * For example, you can display the message on the interface or perform other processing.
 *
 * @param message The received message object. It contains the message content and other related information.
 */
 public void onReceivedMessage(ARTCAIChatMessage message);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessage	The received message, including its content and metadata.

onUserMessageUpdated

Triggered when fields in a message sent by the user are updated.

/**
 * Triggered when fields in a message sent by the user are updated.
 *
 * @param message The message sent by the user.
 */
public void onUserMessageUpdated(ARTCAIChatMessage message);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessage	The message sent by the user.

onAgentResponseStateChange

Triggered when the agent's response state changes.

 /**
  * Triggered when the agent's response state changes.
  *
  * @param agentState The new state of the agent.
  * @param requestId The sentence ID related to the response state change.
  */
public void onAgentResponseStateChange(ARTCAIChatAgentState agentState, String requestId);

Parameters:

Parameter	Type	Description
agentState	ARTCAIChatAgentState	The state of the agent.
requestId	String	The corresponding request ID. Can be empty.

onMessagePlayStateChange

Triggered when the text-to-speech playback state changes.

 /**
  * Triggered when the text-to-speech playback state changes.
  *
  * @param message The message object.
  * @param state The playback state of the message.
*/
public void onMessagePlayStateChange(ARTCAIChatMessage message, ARTCAIChatMessagePlayState state);

Parameters:

Parameter	Type	Description
message	ARTCAIChatMessage	The message object for text-to-speech playback.
state	ARTCAIChatMessagePlayState	The playback state of the message.

onErrorOccurs

Triggered when an error occurs.

 /**
  * An error occurred.
  * @param error
  * @param requestId
 */
public void onErrorOccurs(ARTCAIChatError error, String requestId)

Parameters:

Parameter	Type	Description
error	ARTCAIChatError	The error information.
requestId	String	The corresponding request ID. Can be empty.

onReceivedCustomMessage

Triggered when a custom message is received.

/**
 * A custom message is received.
 * This callback is triggered when you call an OpenAPI operation to send a custom message. The AICall SDK receives this message.
 * @param text The custom message.
 */
public void onReceivedCustomMessage(String  text)

Parameters:

Parameter	Type	Description
text	String	The received custom message.

ARTCAIChatAttachmentUploader

registerAttachmentUploadCallback

Registers an upload callback for attachments.

 /**
   * Registers an upload callback for attachments.
   * @param callback
   */
public abstract void registerAttachmentUploadCallback(ARTCAIChatAttachmentUploader.IARTCAIChatAttachmentUploadCallback callback);

Parameters:

Parameter	Type	Description
callback	IARTCAIChatAttachmentUploadCallback	The callback for the attachment upload result.

addAttachment

Adds an attachment object.

 /**
   * Adds an attachment.
   * @param attachment
   */
public  abstract void addAttachment(ARTCAIChatAttachmentUploader.ARTCAIChatAttachment attachment);

Parameters:

Parameter	Type	Description
attachment	ARTCAIChatAttachment	The attachment object.

removeAttachment

Removes an attachment object.

 /**
   * Removes an attachment.
   * @param attachment
   */
public  abstract void removeAttachment(ARTCAIChatAttachmentUploader.ARTCAIChatAttachment attachment);

Parameters:

Parameter	Type	Description
attachment	ARTCAIChatAttachment	The attachment object.

getAttachmentList

Retrieves the list of attachments.

 /**
   * Gets the list of attachments.
   */
public abstract List<ARTCAIChatAttachment> getAttachmentList()

allUploadSussess

Checks whether all attachments are successfully uploaded.

 /**
   * Checks if all attachments have been uploaded.
   */
 public abstract boolean allUploadSussess();

IARTCAIChatAttachmentUploadCallback

onSuccess

Triggered when the upload is successful.

/**
  * The upload is successful.
 */
public void onSuccess(ARTCAIChatAttachment attachment) {}

onFailure

Triggered when the upload fails.

 /**
   * The upload failed.
   * @param error The returned error information.
   */
public void onFailure(ARTCAIChatAttachment attachment, ARTCAIChatEngine.ARTCAIChatError error) {}

Parameters:

Parameter	Type	Description
attachment	ARTCAIChatAttachment	The attachment object.
error	ARTCAIChatError	The reason why the upload failed.

onProgress

Reports the upload progress.

 /**
   * The upload progress.
   * @param progress
   */
public void onProgress(ARTCAIChatAttachment attachment, int progress) {}

Parameters:

Parameter	Type	Description
attachment	ARTCAIChatAttachment	The attachment object.
progress	int	The upload progress. Valid values: 0 to 100.