Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

Chatbot Integration

Getting started

  1. Platform SDK: Integrate your app (iOS, Android, or Web) with Hyphenate IM services.
  2. Webhooks: Set up webhooks.
  3. Hyphenate Console: Give your chatbot an identity and a voice by creating a Hyphenate IM account for the bot.

Bot Integration

Once you've integrated Hyphenate's IM services, take it a step further and initiate the messaging through your chatbot. For example, a chatbot can greet guests by sending a message via the REST API.

First, your chatbot will need an authentication token.


Obtain an authentication token by making an authentication API request.

  • You can find parameters org_name, app_name, client_id, and client_secret from Hyphenate console.
    org_name and app_name are part of API key (appKey) separated by #, org_name#app_name.
  • Keep "grant_type": "client_credentials" in header.

The authentication API will return a value for access_token, which you will need for API requests later.

  "access_token": "YWMtwtNUVKAawEewTWeWqqwAAAVlUV6g4R6AW-ocnPbw5FiY75pr7LRWcl_c",
  "expires_in": 5183999,
  "application": "5c430490-2113-11e6-baac-5f6b2aba06f8"

Send Message from Bot

Once you obtain the access_token, you can send a text message “Hello friend, nice to meet you!” on behalf of the bot from your developer server via the REST API POST method Send a message

Example curl request

curl -X POST - -header "Content-Type: application/json" - -header "Accept: application/json" - -header "Authorization: Bearer YWMtwtNUVKAawEewTWeWqqwAAAVlUV6g4R6AW-ocnPbw5FiY75pr7LRWcl_c" -d "{
  \"target_type\": \"users\",
  \"target\": [
  \"msg\": {
    \"type\": \"txt\",
    \"msg\": \"Hello friend, nice to meet you!\"
  \"from\": \"the bot\",
  \"ext\": {
    \"bot\": \"If you can't tell, does it matter?\"
}" "https://api.hyphenate.io/hyphenatedemo/hyphenatedemo/messages"

User Message Receiving

Add chatManager delegate method:

[[EMClient sharedClient].chatManager addDelegate:self];

Delegate method of receiving EMConversationModel objects:

- (void)messagesDidReceive:(NSArray *)aMessages;

Option 1 - EMMessage object:

// Message body
EMMessageBody *messageBody = lastMessage.body;
switch (messageBody.type) {
    case EMMessageBodyTypeText:
        NSString *messageContent = ((EMTextMessageBody *)messageBody).text;

Option 2 - EMConversationModel (conversation) object:

NSArray *conversations = [[EMClient sharedClient].chatManager getAllConversations];
EMConversationModel *conversation = [conversations lastObject];  
// Conversation Title
NSString *conversationTitle = conversation.title;
// Message
EMMessage *lastMessage = [conversation latestMessage];
// Message body
EMMessageBody *messageBody = lastMessage.body;
switch (messageBody.type) {
    case EMMessageBodyTypeText:
        NSString *messageContent = ((EMTextMessageBody *)messageBody).text;

User Message Replying

Here an iOS guest replies, “Hello, bot!”, in the chat.

// Compose message
EMTextMessageBody *messageBody = [[EMTextMessageBody alloc] initWithText:@“Are you real?];
EMMessage *message = [[EMMessage alloc] initWithConversationID:recipientUsername from:senderUsername to:recipientUsername body:messageBody ext:nil];
    message.chatType = messageType; // EMChatTypeChat, EMChatTypeGroupChat, EMChatTypeChatRoom

// Send message
[[EMClient sharedClient].chatManager sendMessage:message progress:nil completion:nil];


Set up webhooks to send an event to your application server when a user sends the chatbot a message. See webhooks response format for detailed instructions. Then process the message content on your development server with whatever chatbot algorithms or routines you want and return with appropriate responses.

Example webhook event:

     "bodies": [                     // message bodies
         "msg": "hhhhhh",            // message content
         "type": "txt"               // content type, txt: text message, img: picture, loc: location message, audio: audio clip, video: video clip.
         "length": 3,                // clip length, in seconds, only available for audio or video messages
         "url": "",                  // url for media files, i.e. picture, audio clips
         "filename": "22.png",       // file name for pictures, audio clips, etc.
         "secret": "pCY80PdfEeO4Jh9URCOfMQWU9QYsJytynu4n-yhtvAhmt1g9",    //secret to get files, i.e. picture, audio clips
         "lat": 39.983805,           // latitude, only for location message
         "lng": 116.307417,          // longitude, only for location message
         "addr": "San Francisco, CA" // address, only for location message
     "ext": {                        // customized extension
         "key1": "value1",           // key and values


Chatbot Integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.