XM(Messenger) API

Content

  1. Sign up
    1. Validate email
    2. User registration
  2. Authentication
    1. Login
  3. Messages
    1. List messages
    2. Send a message
    3. Edit a message
    4. Delete a message
    5. Forward a message
    6. Bookmark a message
    7. Pin a message
    8. Unpin a message
    9. React to a message
    10. Remove reaction from a message
  4. Chats
    1. Chats list
    2. Create a chat
    3. Update a chat
    4. Delete a chat
    5. Leave a chat

1. Sign up

This section contains the APIs that are used to manage user registration.

1.1. Validate email

Sends a 6-digit code to the provided email address. The user will use this code during in the user registration step.

🌐 [POST] https://xm.iptp.dev/xm/signup/validate-email

curl --location --request POST 'https://xm.iptp.pe/xm/signup/validate-email?email={emailAddress}'

➡️ Parameters

Send the user email address as a param request.

Name Category Type Required Description
email Request param string Yes The user email address.

⬅️ Returns

Returns a successful HTTP status: 200 (OK) if the email address is a valid email address, and it is not already registered. Returns an error status of 400 (Bad request) if the email is not valid of if it is already registered.

1.2. User registration

Creates a XM user account with the provided user information. If a invite code is provided, it will accept the pending invitation.

🌐 [POST] https://xm.iptp.dev/xm/signup/validate-email

curl --location --request POST 'https://xm.iptp.pe/xm/signup?invite={invite}'

➡️ Parameters

Send the user info as a JSON body.

Name Category Type Required Description
invite Request param string No The invite code sent to the user email.
name Body param string Yes The user full name. Min length: 3. Max length: 32.
email Body param string Yes The user email address.
password Body param string Yes The user password. Min length: 8.
password2 Body param string Yes The user password confirmation.
code Body param string Yes The code sent in the validate email step.

⬅️ Returns

Returns the userId, sessionId, access_token, and the refresh_token with a successful HTTP status of 200 (OK).

{
  "userId": "6e44999a9c9b",
  "sessionId": "613B3A46A29366CF730B81CF2434530F",
  "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI2ZTQ0OTk5YTljOWIiLCJpYXQiOjE2NDkxOTAwNjksImV4cCI6MTY0OTE5MTg2OX0.pT4PGngSvXYAnqTu-mEeQtCmpQM7K1kdG8NQfMJa8yE4x84Oiu61hSAJVWiYUeJ4j610nJNwJc2ZVLRyf88Tug",
  "refresh_token": "f6d02940-a9dc-44b3-b7a3-c5c0a9fad75e"
}
Name Description
userId It is the id of your user.
sessionId It is the id of your device. It is used as a param of the sync method.
access_token Required to get access to the API. It will last for 30 minutes. After that, it will become invalid.
refresh_token You can refresh your access_token by using this refresh token.

Error messages:

Status Message
400 (Bad Request) Provided passwords do not match.
400 (Bad Request) Wrong registration code.
400 (Bad Request) Email already registered.

2. Authentication

All API requests required to be authenticated via bearer auth ( e.g. --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9'). API requests without authentication will fail with a 401: Unauthorized error.

2.1. Login

Retrieves an access_token to get access to the API.

🌐 [POST] https://xm.iptp.dev/xm/auth/login

curl --location --request POST 'https://xm.iptp.dev/xm/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "user@company.com",
    "password": "s0m3P@ssw0rd"
}'

➡️ Parameters

Send the user credentials in JSON format as the body request.

Name Category Type Required Description
email Body param string Yes The user email address.
password Body param string Yes The user password.

⬅️ Returns

Returns the access_token, the refresh_token and the sessionId if the provided credentials were valid.

Successful HTTP status: 200 (Ok),

{
  "userId": "6e44999a9c9b",
  "sessionId": "613B3A46A29366CF730B81CF2434530F",
  "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI2ZTQ0OTk5YTljOWIiLCJpYXQiOjE2NDkxOTAwNjksImV4cCI6MTY0OTE5MTg2OX0.pT4PGngSvXYAnqTu-mEeQtCmpQM7K1kdG8NQfMJa8yE4x84Oiu61hSAJVWiYUeJ4j610nJNwJc2ZVLRyf88Tug",
  "refresh_token": "f6d02940-a9dc-44b3-b7a3-c5c0a9fad75e"
}
Name Description
userId It is the id of your user.
sessionId It is the id of your device. It is used as a param of the sync method.
access_token Required to get access to the API. It will last for 30 minutes. After that, it will become invalid.
refresh_token You can refresh your access_token by using this refresh token.

Returns the error 401 if the provided credentials are not valid.

HTTP status of 401 (Unauthorized).

{
  "status": 401,
  "error": "Unauthorized",
  "timestamp": 1649190127318,
  "message": "Not authorized",
  "details": "Bad credentials"
}

3. Messages

3.1 List Messages

Lists the last 20 messages in a room.

🌐 [POST] https://xm.iptp.dev/xm/auth/login

curl --location --request GET 'https://xm.iptp.dev/xm/api/messages?chatId={chatId}' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

➡️ Parameters

Name Type Required Description
chatId string yes Id of the chat from which messages will be returned, it must be a valid id.
offset long no Sequence of the message from which previous messages will be returned. If not specified, default value is 0.
type int no Message type, allowed values are: 2 (images), 3 (audios), 4 (videos) and 20 (files).
search string no Search keyword. If provided, must be at least 3 characters length.
starred boolean no Whether the messages are marked as bookmarked or not.

⬅️ Returns

Return the message list sorted in descending order by message date, the pinned message (if present) and the last time of activity of the chat partner if the chat is a direct chat (not a group). Each message will include content attachments if present.

Successful HTTP status: 200 (Ok)

See response body 

{
  "pinnedMessage": {
    "id": {
      "chatId": "6a16c7ed9181",
      "messageId": "8a7e6d957cc1"
    },
    "sender": {
      "id": "8c391e185d79",
      "name": "Steven",
      "email": "phuong@iptp.vn"
    },
    "message": "SGVsbG8gQW5kcmUsIEkgcHVzaGVkIHRoZSBjb2Rl",
    "msgDate": "2022-03-19T13:30:29.736+00:00",
    "type": 1,
    "updated": false,
    "deleted": false,
    "internal": false,
    "forwarded": false,
    "file": null,
    "sequence": 1470,
    "quotedMessage": null,
    "updatedAt": null,
    "unread": false,
    "starred": false,
    "readByAllPartners": false,
    "reactions": null,
    "pinned": true,
    "taggedUsers": []
  },
  "partnerLastTimeActivity": "2022-04-06T03:06:53.000+00:00",
  "messages": [
    {
      "id": {
        "chatId": "6a16c7ed9181",
        "messageId": "ee0842c3cdeb"
      },
      "sender": {
        "id": "0bbac78ae7d5",
        "name": "André Bedregal",
        "email": "andreb@iptp.pe"
      },
      "message": "T2s=",
      "msgDate": "2022-03-22T03:25:45.099+00:00",
      "type": 1,
      "updated": false,
      "deleted": false,
      "internal": false,
      "forwarded": false,
      "file": null,
      "sequence": 1544,
      "quotedMessage": null,
      "updatedAt": null,
      "unread": false,
      "starred": true,
      "readByAllPartners": true,
      "reactions": [
        {
          "reaction": "😃",
          "user": {
            "id": "0bbac78ae7d5",
            "name": null,
            "email": null
          },
          "reactionDate": "2022-03-31T21:47:10.000+00:00"
        }
      ],
      "pinned": false,
      "taggedUsers": null
    }
  ]
}

3.2 Send a message

Sends a message to the specified chat.

🌐 [POST] https://xm.iptp.dev/xm/api/chats/{chatId}/messages

curl --location --request POST 'https://xm.iptp.dev/xm/api/chats/4984d45b5a31/messages' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": "aGkgQFt1c2VyOjY0MmU3MzE4MTMzNl0gdGhpcyBpcyBhIHRlc3Q=",
    "internal": true,
    "quotedMessageId": null,
    "taggedUserIds": ["642e73181336"]
}'

➡️ Parameters

Name Category Type Required Description
chatId Request param string yes Id of the chat room where the message will be sent.
message Body param string yes Text message.
internal Body param boolean no Whether the message is internal or not. It will only work on Live Assistance chats, otherwise it will be ignored.
quotedMessageId Body param string yes Id of the quoted messaged.
taggedUserIds Body param array yes List of the user id tagged in the message.

⬅️ Returns

Returns the message id of the created message.

Successful HTTP status: 201 (Created)

{
  "chatId": "4984d45b5a31",
  "messageId": "8ef1ca1e8bb1"
}

3.3. Edit a message

Update the content of specified message.

🌐 [PUT] https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}

curl --location --request PUT 'https://xm.iptp.dev/xm/api/chats/4984d45b5a31/messages/8ef1ca1e8bb1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": "aGkgQFt1c2VyOjY0MmU3MzE4MTMzNl0gdGhpcyBpcyBhIHRlc3Q=",
    "taggedUserIds": ["642e73181336"]
}'

➡️ Parameters

Name Category Type Required Description
chatId Request param string yes Id of the chat room.
messageId Request param string yes Id of the message to be updated.
message Body param string yes The new content of the message.
taggedUserIds Body param string yes List of the user id tagged in the message.

⬅️ Returns

Return nothing.

Successful HTTP status: 204 (No content)

3.4. Delete a message

Delete the specified message.

🌐 [DELETE] https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}

curl --location --request DELETE 'https://xm.iptp.dev/xm/api/chats/4984d45b5a31/messages/8ef1ca1e8bb1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

➡️ Parameters

Name Category Type Required Description
chatId Request param string yes Id of the chat room.
messageId Request param string yes Id of the message to be deleted.

⬅️ Returns

Return nothing.

Successful HTTP status: 204 (No content)

3.5. Forward a message

Forward a specified message from a source chat to a destination chat.

🌐 [POST] https://xm.iptp.dev/xm/api/messages/forward

curl --location --request POST 'https://xm.iptp.dev/xm/api/messages/forward' \
--header 'Authorization : Bearer eyJhbGciOiJIUzUxMiJ9......' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sourceChatId": "4984d45b5a31",
    "messageId": "8ef1ca1e8bb1",
    "destChatId": "d056d1b6a136"
}'

➡️ Parameters

Name Category Type Required Description
sourceChatId Body param string yes Id of the source chat from where message will be forwarded.
messageId Body param string yes Id of the message.
destChatId Body param string yes Id of the destination chat to where message will be forwarded.

⬅️ Returns

Returns the message id of the new forwarded message.

Successful HTTP status: 201 (Created).

{
  "chatId": "d056d1b6a136",
  "messageId": "3b71e864fd8c"
}

3.6. Bookmark a message

Bookmark a message. If the message is already bookmarked, a call to this endpoint will delete the bookmark.

🌐 [POST] https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}/star

curl --location --request POST 'https://xm.iptp.pe/xm/api/chats/4984d45b5a31/messages/8ef1ca1e8bb1/star' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

➡️ Parameters

Name Category Type Required Description
sourceChatId Body param string yes The id of the chat to which the message belongs.
messageId Body param string yes The id of the message.

⬅️ Returns

Returns nothing.

Successful HTTP status: 204 (No content).

ℹ️ Notes

After a successful call to this endpoint, the API will send an event in the reactionEvents property of the sync method response. This event contains information of the messageId and the chatId, and whether the message is bookmarked ( starred) or not.

{
  "reactionEvents": [
    {
      "chatId": "4984d45b5a31",
      "messageId": "8ef1ca1e8bb1",
      "userId": "2992e506ecc8",
      "starred": false,
      "reaction": null,
      "date": null
    }
  ]
}

3.7 Pin a message

XM allows chats to have one “pinned” message on it. All chat members can pin/unpin a message at any time. If the chat already has a pinned message, the XM server will unpin this pinned message, and then it will pin the message with id: messageId. Only non-deleted messages of types: 1 (text), 2 (image), 3 (audio), 4 (video), or 20 (file) can be pinned.

🌐 [POST] https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}/pin

curl --location --request POST 'https://xm.iptp.dev/xm/api/chats/6a16c7ed9181/messages/531a16c80e00/pin' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

➡️ Parameters

Name Category Type Required Description
sourceChatId Body param string yes The id of the chat to which the message belongs.
messageId Body param string yes The id of the message.

⬅️ Returns

Return nothing in case of a successful request.

Successful HTTP status: 204 (No content).

Return an error response with an HTTP Status of 400: Bad Request in case of an unsupported message type or if the message has already been deleted.

ℹ️ Notes

The server will send the information about the pinned message asynchronously as sync events. If the chat doesn’t already have a pinned message, the server will send two sync events:

  • A message event of type: 9 so the client can render it on the chat window as “The user has pinned the message test1”.
  {
  "id": {
    "chatId": "6a16c7ed9181",
    "messageId": "b74781ce0148"
  },
  "sender": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "message": "test1",
  "msgDate": "2022-02-23T17:43:13.648+00:00",
  "type": 9,
  "updated": false,
  "deleted": false,
  "internal": false,
  "forwarded": false,
  "file": null,
  "sequence": 1349,
  "quotedMessage": null,
  "updatedAt": null,
  "unread": true,
  "starred": false,
  "readByAllPartners": false,
  "reactions": null,
  "pinned": false
}
  • A pin message event containing the information of the pinned message 531a16c80e00: test1 as follows:
{
  "message": {
    "id": {
      "chatId": "6a16c7ed9181",
      "messageId": "531a16c80e00"
    },
    "sender": {
      "id": "8c391e185d79",
      "name": "Steven",
      "email": "phuong@iptp.vn"
    },
    "message": "test1",
    "msgDate": "2022-02-23T16:54:58.092+00:00",
    "type": 1,
    "updated": false,
    "deleted": false,
    "internal": false,
    "forwarded": false,
    "file": null,
    "sequence": 1340,
    "quotedMessage": null,
    "updatedAt": null,
    "unread": false,
    "starred": false,
    "readByAllPartners": false,
    "reactions": null,
    "pinned": true
  },
  "user": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "pinned": true
}

If the chat already has a pinned message (let’s say it has pinned the message with id: 30112e9e6875: test0 and we want to pin the message 531a16c80e00: test1), the server will addtionaly send two sync events with the information of the unpinned message 30112e9e6875: test2 as follows:

  • A message event of type: 8 so the client can render it on the chat window as “The user has unpinned the message test0”.
{
  "id": {
    "chatId": "6a16c7ed9181",
    "messageId": "4743644a0bec"
  },
  "sender": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "message": "test0",
  "msgDate": "2022-02-23T17:46:50.617+00:00",
  "type": 8,
  "updated": false,
  "deleted": false,
  "internal": false,
  "forwarded": false,
  "file": null,
  "sequence": 1350,
  "quotedMessage": null,
  "updatedAt": null,
  "unread": true,
  "starred": false,
  "readByAllPartners": false,
  "reactions": null,
  "pinned": false
}
  • A pin message event containing the information of the unpinned message 30112e9e6875: test0 as follows:
{
  "message": {
    "id": {
      "chatId": "6a16c7ed9181",
      "messageId": "30112e9e6875"
    },
    "sender": {
      "id": "8c391e185d79",
      "name": "Steven",
      "email": "phuong@iptp.vn"
    },
    "message": "test0",
    "msgDate": "2022-02-23T16:55:41.838+00:00",
    "type": 1,
    "updated": false,
    "deleted": false,
    "internal": false,
    "forwarded": false,
    "file": null,
    "sequence": 1343,
    "quotedMessage": null,
    "updatedAt": null,
    "unread": false,
    "starred": false,
    "readByAllPartners": false,
    "reactions": null,
    "pinned": false
  },
  "user": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "pinned": false
}

3.8 Unpin a message

To unpin a message from a chat (without pinning any other message), send a DELETE request to:

https://xm.iptp.dev/xm/api/chats/{chatId}/messages/unpin

Where:

Name Type Description
chatId string (Required) The id of the chat that has the pinned message.

There is no need to specify the id of the pinned message because the server will discover it (if any) based on the chat id and then unpin it.

Sample request with cURL

To unpin a pinned message from the chat with id: 6a16c7ed9181, send the following request:

curl --location --request DELETE 'https://xm.iptp.dev/xm/api/chats/6a16c7ed9181/messages/unpin' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

Sample server response

In case the chat has a pinned message, the server will unpin it and return a successful empty response with an HTTP status of 204 (No Content). However, the server will send the information about the unpinned message asynchronously as sync events:

  • A message event of type: 8 so the client can render it on the chat window as “The user has unpinned the message test1”.
{
  "id": {
    "chatId": "6a16c7ed9181",
    "messageId": "717d28fee4d9"
  },
  "sender": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "message": "test1",
  "msgDate": "2022-02-23T18:12:30.844+00:00",
  "type": 8,
  "updated": false,
  "deleted": false,
  "internal": false,
  "forwarded": false,
  "file": null,
  "sequence": 1354,
  "quotedMessage": null,
  "updatedAt": null,
  "unread": true,
  "starred": false,
  "readByAllPartners": false,
  "reactions": null,
  "pinned": false
}
  • A pin message event containing the information of the unpinned message 531a16c80e00: test1 as follows:
{
  "message": {
    "id": {
      "chatId": "6a16c7ed9181",
      "messageId": "531a16c80e00"
    },
    "sender": {
      "id": "8c391e185d79",
      "name": "Steven",
      "email": "phuong@iptp.vn"
    },
    "message": "test1",
    "msgDate": "2022-02-23T16:54:58.092+00:00",
    "type": 1,
    "updated": false,
    "deleted": false,
    "internal": false,
    "forwarded": false,
    "file": null,
    "sequence": 1340,
    "quotedMessage": null,
    "updatedAt": null,
    "unread": false,
    "starred": false,
    "readByAllPartners": false,
    "reactions": null,
    "pinned": false
  },
  "user": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "pinned": false
}

If the chat does not have a pinned message, the server will return an error response with an HTTP status of 404 (Not Found).

3.9 React to a message

XM allows users to react to any messages (own and other’s messages) with any emoji.

React to a message

To react to a message in a chat, send a POST request to with the reaction (emoji) in the body:

https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}/react

Where:

Name Type Description
chatId string (Required) The id of the chat to which the message belongs.
messageId string (Required) The id of the message.

You can send any emoji included in app/features/chatbox/emoji.js.

Sample request with cURL

To pin the message with id: ee0842c3cdeb on the chat with id: 6a16c7ed9181, send the following request:

curl --location --request POST 'https://xm.iptp.dev/xm/api/chats/6a16c7ed9181/messages/ee0842c3cdeb/react' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: text/plain' \
--data-raw '👍'

20.1.2 Sample server response

In case of a successful request, the server will return an empty response with an HTTP status of 204 (No content). However, the server will send the information about the message reaction asynchronously as a sync event (in the sync method response).

  • This “reaction event” includes information about the user who has reacted to the message, the reacted message and the reaction emoji as well.
{
  "chatId": "6a16c7ed9181",
  "messageId": "ee0842c3cdeb",
  "userId": "0bbac78ae7d5",
  "starred": false,
  "reaction": "👍",
  "date": "2022-03-24T17:36:31.000+00:00"
}

3.10. Remove reaction from a message

To remove a reaction from a message in a chat, send a DELETE request to:

https://xm.iptp.dev/xm/api/chats/{chatId}/messages/{messageId}/react

Where:

Name Type Description
chatId string (Required) The id of the chat that has the pinned message.
messageId string (Required) The id of the message.

Sample request with cURL

To remove the reaction from the message with id ee0842c3cdeb of the chat with id: 6a16c7ed9181, send the following request:

curl --location --request DELETE 'https://xm.iptp.dev/xm/api/chats/6a16c7ed9181/messages/ee0842c3cdeb/react' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

Sample server response

In case the chat has a pinned message, the server will unpin it and return a successful empty response with an HTTP status of 204 (No Content). However, the server will send the information about the unpinned message asynchronously as sync events:

  • A message event of type: 8 so the client can render it on the chat window as “The user has unpinned the message test1”.
{
  "id": {
    "chatId": "6a16c7ed9181",
    "messageId": "717d28fee4d9"
  },
  "sender": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "message": "test1",
  "msgDate": "2022-02-23T18:12:30.844+00:00",
  "type": 8,
  "updated": false,
  "deleted": false,
  "internal": false,
  "forwarded": false,
  "file": null,
  "sequence": 1354,
  "quotedMessage": null,
  "updatedAt": null,
  "unread": true,
  "starred": false,
  "readByAllPartners": false,
  "reactions": null,
  "pinned": false
}
  • A pin message event containing the information of the unpinned message 531a16c80e00: test1 as follows:
{
  "message": {
    "id": {
      "chatId": "6a16c7ed9181",
      "messageId": "531a16c80e00"
    },
    "sender": {
      "id": "8c391e185d79",
      "name": "Steven",
      "email": "phuong@iptp.vn"
    },
    "message": "test1",
    "msgDate": "2022-02-23T16:54:58.092+00:00",
    "type": 1,
    "updated": false,
    "deleted": false,
    "internal": false,
    "forwarded": false,
    "file": null,
    "sequence": 1340,
    "quotedMessage": null,
    "updatedAt": null,
    "unread": false,
    "starred": false,
    "readByAllPartners": false,
    "reactions": null,
    "pinned": false
  },
  "user": {
    "id": "0bbac78ae7d5",
    "name": "André Bedregal",
    "email": "andreb@iptp.pe"
  },
  "pinned": false
}

If the chat does not have a pinned message, the server will return an error response with an HTTP status of 404 (Not Found).