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

IM Account Registration

Hyphenate ID Naming Rules

Here are the naming rules for Hyphenate IM usernames (Hyphenate ID):

  • Use a combination of English letters (upper and lower) and/or numbers.
  • Only allow the “[a-zA-Z0-9_-.]*” (a~z uppercase and lowercase letters, numbers, underline, dash, period).
  • No spaces, '@', '#', '\', '/', ',', or other special characters.

Users' Hyphenate ID and app username do not need to be identical, but the app must be able to map the relationship of those two accounts.

For instance, the user 'Apple' has the Hyphenate ID "apple" and app username "apple@hyphenate.io". If 'Apple' logs into the app using the username "apple@hyphenate.io", your system must pull the Hyphenate ID "apple" from the app server and use it to log into the Hyphenate service in order to deliver the message on the user's behalf.

Register a Hyphenate IM Account (Hyphenate ID and Password)

Try it!

Registration Types: Open and Authorized

  • Open registration: This does not require administrator authentication information during the registration process.
  • Authorized registration: This requires administrator authentication information during the registration process.

Recommendation

We recommend Authorized registration to prevent malicious attempts of registering fraudulent accounts.

You can change the registration permissions on the Hyphenate Console

Create a User

POST/{org_name}/{app_name}/users

Parameters

URL Parameters

Name Type Description
token String (For Authorized registration only) The token for the registration API can be obtained by authentication request.

Request Body

Name Type Description
username String Request body - The username or Hyphenate ID is the primary key to access the Hyphenate service on behalf of a user.
password String Request body - The password is only used for logging into the Hyphenate IM server, and should not be the same as the password to log into the app
nickname String Request body - Optional - The nickname is used as the display name for iOS push notifications.

Example

Request body

{
  "username":"apple",
  "password":"12345"
}

curl

curl -X POST -H "Authorization: Bearer YWMt39RfMMOqEeKYE_GW7tu81AAAAT71lGijyjG4VUIC2AwZGzUjVbPp_4qRD5k" -i  "https://api.hyphenate.io/hyphenatedemo/fruitworld/users" -d '{"username":"apple","password":"123456"}'

Response

{
    "action" : "post",
    "application" : "a2e433a0-ab1a-11e2-a134-85fca932f094",
    "params" : { },
    "path" : "/users",
    "uri" : "https://api.hyphenate.io/hyphenate/fruitworld/users",
    "entities" : [ {
        "uuid" : "7f90f7ca-bb24-11e2-b2d0-6d8e359945e4",
        "type" : "user",
        "created" : 1368377620796,
        "modified" : 1368377620796,
        "username" : "apple",
        "activated" : true
        }
      } ],
      "timestamp" : 1368377620793,
      "duration" : 125,
      "organization" : "hyphenatedemo",
      "applicationName" : "fruitworld"
}

Notes

Open Registration

Note

The only difference between open and authorized requests is that authorized requires an an authentication token obtained from Authentication Request, while open registration does not.

Example

curl

curl -X POST -i "https://api.hyphenate.io/hyphenatedemo/fruitworld/users" -d '{"username":"apple","password":"12345"}'

Response

{
    "action" : "post",
    "application" : "a2e433a0-ab1a-11e2-a134-85fca932f094",
    "params" : { },
    "path" : "/users",
    "uri" : "https://api.hyphenate.io/hyphenatedemo/fruitworld/users",
    "entities" : [ {
        "uuid" : "7f90f7ca-bb24-11e2-b2d0-6d8e359945e4",
        "type" : "user",
        "created" : 1368377620796,
        "modified" : 1368377620796,
        "username" : "apple",
    "activated" : true
    } ],
    "timestamp" : 1368377620793,
    "duration" : 125,
    "organization" : "hyphenatedemo",
    "applicationName" : "fruitworld"
}

Create Users in Batch

To create multiple IM accounts at the same time, use the same method, but modify the request body by passing an array of registration data in JSON.

Example

Request body

[
    {
        "username":"apple", 
        "password":"12345"
    }, 
    {
        "username":"orange", 
        "password":"12345"
    },
]

curl

curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://api.hyphenate.io/hyphenatedemo/fruitworld/users" -d '[{"username":"apple", "password":"12345"}, {"username":"orange", "password":"12345"}]'

Response

{
    "action" : "post",
    "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "params" : { },
    "path" : "/users",
    "uri" : "https://api.hyphenate.io/hyphenatedemo/fruitworld/users",
    "entities" : [ {
        "uuid" : "de73238a-31ca-11e4-bdc9-9fdda213fcaa",
        "type" : "user",
        "created" : 1409570811320,
        "modified" : 1409570811320,
        "username" : "apple",
        "activated" : true
    }, {
        "uuid" : "de86365a-31ca-11e4-aecf-9509b836c0d6",
        "type" : "user",
        "created" : 1409570811445,
        "modified" : 1409570811445,
        "username" : "orange",
        "activated" : true
    }, 
    ... 
    ],
    "timestamp" : 1409570811312,
    "duration" : 802,
    "organization" : "hyphenatedemo",
    "applicationName" : "fruitworld"
}

Notes

We recommend that you register no more than 60 users at a time to avoid the size limitation of 5 KB for the request body. You'll get an error code 413 in response if your request exceeds 5 KB.

For the majority of developers, we recommend using REST APIs to create a Hyphenate user account and associate the user account directly upon registration with your developer backend. Communication between servers is more reliable in terms of network stability, which results in better performance and reduces the likelihood of data inconsistency.

However, it's possible to do this from the mobile client as well.

Next Section: User Management

IM Account Registration


Suggested Edits are limited on API Reference Pages

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