Third-party Server API

Third Server all new and changed API records.

Overview

Before you access the api, you must have been the SendingMe user and you must hava get oauth token from Oauth API - API3.Fetch access token. If you have not authorize, you cannot call API1(Get the server_access_token). The API accessed by the third-party server, each thirty-party can only bind one account. This account serves as the official account of the third party in sendingMe. When you get the server_access_token, you can access the following API

Third-party Server API

Descriptions for accessing the IM API from the third-party server

API1. Get the server_access_token

POST /_api/client/r0/oauth/bind-server-client

create server access token.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The access token get by /login API

Request body

Name Type Description
client_secret string client_secret is secret that SendingMe gives to the thirty party

Request body example

{
  "client_secret": "KzfTxIfViRwUnTagbykMLOdNhOqsEedB"
}

Responses

Status Description
200 Information about the server access token.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response

Name Type Description
server_access_token string Required: The Server access token. 
{
  "server_access_token": "KzfTxIfViRwUnTagbykMLOdNhOqsEedB"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

API2. Upload files to sendingMe

POST /_api/client/r0/server_upload

upload file to sendingMe
Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
Content-Type string The content type of the file being uploaded
query parameters
Name Type Description
filename string The name of the file being uploaded

Request body

Request body example

"<bytes>"

Responses

Status Description
200 The MXC URI for the uploaded content.
403

The user does not have permission to upload the content. Some reasons for this error include:

  • The server does not permit the file type.
  • The user has reached a quota for uploaded content.
413 The uploaded content is too large for the server.
429 This request was rate-limited.

200 response

Name Type Description
content_uri string Required: The MXC URI to the uploaded content.
content_url string Required: The public url to get the content. 
{
  "content_uri": "mxc://example.com/KHICdrFFSAXigXHqUBoXViRW",
  "content_url": "http://hs.sending.me/_api/media/r0/download/hs.sending.me/KHICdrFFSAXigXHqUBoXViRW"
}

403 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_FORBIDDEN",
  "error": "Cannot upload this content"
}

413 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_TOO_LARGE",
  "error": "Cannot upload files larger than 100mb"
}

429 response

RateLimitError
Name Type Description
errcode string Required: The M_LIMIT_EXCEEDED error code
error string A human-readable error message.
retry_after_ms integer The amount of time in milliseconds the client should wait before trying the request again. 
{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

API3. Server create squad

POST /_api/client/r0/server/createRoom

Create a new squad
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
creation_content CreationContent Required: Type “m.space” represents a squad. If no “creation_content” in parameters, ｂy default the room will be created
initial_state [StateEvent] Required:

A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

Takes precedence over events set by preset, but gets overridden by name and topic keys.
name string Required: If this is included, an m.room.name event will be sent into the room to indicate the name of the room. See Room Events for more information on m.room.name.
room_alias_name string Required:

The desired room alias local part. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the same homeserver which created the room. For example, if this was set to “foo” and sent to the homeserver “example.com” the complete room alias would be #foo:example.com.

The complete room alias will become the canonical alias for the room and an m.room.canonical_alias event will be sent into the room.
StateEvent
Name Type Description
content object Required: The content of the event.
state_key string The state_key of the state event. Defaults to an empty string.
type string Required: The type of event to send. “m.room.avatar” represents a avatar of the squad you creates

Request body example

{
  "creation_content": {
    "type": "m.space"
  },
  "initial_state": [
    {
      "content": {
        "url": "mxc://localhost:8080/LyZyBcvugNtgJqHIRZMNyqdj"
      },
      "type": "m.room.avatar"
    }
  ],
  "name": "yhzhang-test1",
  "room_alias_name": "yhzhang-test111"
}

Responses

Status Description
200 Information about the newly created room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response

Name Type Description
room_id string Required: The created room’s ID. 
{
  "room_alias": "#yhzhang-test111:localhost:8080",
  "room_id": "!rbrwRgtDMyheefNQch:localhost:8080"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

API4. Server create room

POST /_api/client/r0/server/createRoom

Create a room　that belongs to a squad．
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
initial_state [StateEvent] Required:

A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

Takes precedence over events set by preset, but gets overridden by name and topic keys.

The type of event to send.
“m.room.join_rules”
A room may have one of the following designations:

public – anyone can join the room without any prior action.
invite – a user must first receive an invite from someone already in the room in order to join.
knock – a user can request an invite to the room. They can be allowed (invited) or denied (kicked/banned) access. Otherwise, users need to be invited in. Only available in rooms which support knocking.
restricted – anyone able to satisfy at least one of the allow conditions is able to join the room without prior action. Otherwise, an invite is required. Only available in rooms which support the join rule.
knock_restricted – a user can request an invite using the same functions offered by the knock join rule, or can attempt to join having satisfied an allow condition per the restricted join rule. Only available in rooms which support the join rule.
private – reserved without implementation. No significant meaning.

“m.space.parents”
The parent squad ID.
canonical: boolean
Optional (default false) flag to denote this parent is the primary parent for the room. When multiple canonical parents are found, the lowest parent when ordering by room ID lexicographically by Unicode code-points should be used.
name string Required: The room name
StateEvent
Name Type Description
content object Required: The content of the event.
state_key string The state_key of the state event. Defaults to an empty string.
type string Required: The type of event to send.

Request body example

{
  "initial_state": [
    {
      "content": {
        "join_rule": "public"
      },
      "type": "m.room.join_rules"
    },
    {
      "content": {
        "canonical": true,
        "via": [
          "localhost:8080"
        ]
      },
      "state_key": "!bOTqPHjJBTVFBQBHdQ:localhost:8080",
      "type": "m.space.parent"
    }
  ],
  "name": "a3"
}

Responses

Status Description
200 Information about the newly created room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response

Name Type Description
room_id string Required: The created room’s ID. 
{
  "room_id": "!sefiuhWgwghwWgh:example.com"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

API5. Send room message

PUT /_api/client/r0/server/send/m.room.message

post message to room.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string Required: The server access token

Request body

Name Type Description
body string The textual representation of this message.
msgtype string Required: The type of message, e.g. m.image, m.text
room_id string A room Id.

Request body example

{
  "content": {
    "body": "https://app-alpha.sending.me",
    "msgtype": "m.text"
  },
  "room_id": "!tuKKVwEACyWeqdBRwN:localhost:8080"
}

Responses

Status Description
200 An ID for the sent event.

200 response

Name Type Description
event_id string Required: A unique identifier for the event. 
{
  "event_id": "!sefiuhWgwghwWgh:example.com"
}

API6. Send AMA activity to Home Page

POST /_api/client/r0/server/createHomePageShow

create ama activity in home page. the curl example.

  curl --location 'http://localhost:8080/_api/client/r0/server/createHomePageShow' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
    --data '{
        "room_id": "!sdWtGNomKuYizKMXaE:localhost:8080",
        "url": "https://beta.soshow.io/#/?space=1ypKddykkbgKW",
        "name": "How To Buy Crypto With NGN Using Cashlink",
        "start_time": 1668769242000,
        "description": "",
        "title": "How To Buy Crypto With NGN Using Cashlink",
        "host": "BinanceAfrica",
        "host_wallet_address": "",
        "host_avatar": "https://pbs.twimg.com/profile_images/1480341292877959169/5AgZD9Gr_normal.jpg",
        "tag_icon": "xxx",
        "tag_text": "xxx",
        "background_image":"aaa",
        "source":"Twitter",
        "co_host_info": [
            {
                "co_host": "Olubxnmi",
                "co_host_wallet_address": "",
                "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg"
            },
            {
                "co_host": "Olubxnmi",
                "co_host_wallet_address": "",
                "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg"
            }
        ],
        "home_page_show_participate":null
    }'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
background_image string the background color of the AMA activity shown in HomePage
co_host string the co host name of the activity
co_host_avatar string the co host avatar of the activity
co_host_wallet_address string the co host wallet address of the activity
description integer the detail of the activity
end_time integer the end_time(ms) of the activity
host string Required: the host name of the activity
host_avatar string Required: the avatar of the host
host_wallet_address string Required: the wallet address of the host
location string the location of the AMA activity
name string Required: the name of activity.
participate_avatar string the avatar of the participate
participate_name string the name of the participate
participate_wallet_address string the wallet address of the participate
room_id string Required: A room Id.
source enum Required: the source of the AMA activity

One of: [Twitter, SendingMe].
start_time integer Required: the start_time(ms) of the activity
tag_icon string the tag image of the activity
title integer Required: the title of the activity
url string Required: the url of the activity

Request body example

{
  "background_color": "aaa",
  "co_host_info": [
    {
      "co_host": "Olubxnmi",
      "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "co_host_wallet_address": ""
    },
    {
      "co_host": "Olubxnmi",
      "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "co_host_wallet_address": ""
    }
  ],
  "description": "",
  "home_page_show_participate": [
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1481661390049976323/ET6nfC1l_normal.jpg",
      "participate_name": "EmekaDinkpa",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1458216078039977989/41pJ4qhA_normal.jpg",
      "participate_name": "PlayoffP_",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1561442464187252736/XnAyBSZo_normal.jpg",
      "participate_name": "Monsiuer_T",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "participate_name": "Olubxnmi",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1192814495636348928/mQBv7aNI_normal.jpg",
      "participate_name": "dbenz_man",
      "participate_wallet_address": ""
    }
  ],
  "host": "BinanceAfrica",
  "host_avatar": "https://pbs.twimg.com/profile_images/1480341292877959169/5AgZD9Gr_normal.jpg",
  "host_wallet_address": "",
  "name": "How To Buy Crypto With NGN Using Cashlink",
  "room_id": "!WJjoOHqhOoizFoNNle:localhost:8080",
  "source": "Twitter",
  "start_time": 1668769242000,
  "tag_icon": "xxx",
  "tag_text": "xxx",
  "title": "How To Buy Crypto With NGN Using Cashlink",
  "url": "https://beta.soshow.io/#/?space=1ypKddykkbgKW"
}

Responses

Status Description
200 An ID of the activity.

200 response

Name Type Description
event_id string A unique identifier for the activity. 
{
  "id": "qzDGfGODhlQuvYXZEdTvHURvDTHCBACy"
}

API7. Update AMA activity in Home Page

PUT /_api/client/r0/server/homePageShow/{id}

update ama activity in home page show. the curl example.

  curl --location --request PUT 'http://localhost:8080/_api/client/r0/server/homePageShow/EsQMVXFgzWRtHpnDgywejHvjpfPGteFs' \
  --header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
  --header 'Content-Type: application/json' \
  --data '{
      "room_id": "!sdWtGNomKuYizKMXaE:localhost:8080",
      "url": "https://beta.soshow.io/#/?space=1ypKddykkbgKW",
      "name": "HOW To Buy Crypto With NGN Using Cashlink",
      "start_time": 1668769242000,
      "description": "",
      "title": " HOW To Buy Crypto With NGN Using Cashlink",
      "host": "BinanceAfrica",
      "host_wallet_address": "",
      "host_avatar": "https://pbs.twimg.com/profile_images/1480341292877959169/5AgZD9Gr_normal.jpg",
      "tag_icon": "xxx",
      "tag_text": "xxx",
      "location":"aaa",
      "source":"Twitter",
      "background_image":"xxx",
      "co_host_info": [
          {
              "co_host": "Olubxnmi",
              "co_host_wallet_address": "",
              "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg"
          },
          {
              "co_host": "Olubxnmi",
              "co_host_wallet_address": "",
              "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg"
          }
      ],
      "home_page_show_participate":null
  }'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
background_image string the background image of the AMA activity
co_host string the co host name of the activity
co_host_avatar string the co host avatar of the activity
co_host_wallet_address string the co host wallet address of the activity
description integer the detail of the activity
end_time integer the end_time(ms) of the activity
host string Required: the host name of the activity
host_avatar string Required: the avatar of the host
host_wallet_address string Required: the wallet address of the host
location string the location of the AMA activity
name string Required: the name of activity.
participate_avatar string the avatar of the participate
participate_name string the name of the participate
participate_wallet_address string the wallet address of the participate
room_id string Required: A room Id.
source enum Required: the source of the AMA activity

One of: [Twitter, SendingMe].
start_time integer Required: the start_time(ms) of the activity
tag_icon string the tag image of the activity
title integer Required: the title of the activity
url string Required: the url of the activity

Request body example

{
  "background_image": "xxx",
  "co_host_info": [
    {
      "co_host": "Olubxnmi",
      "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "co_host_wallet_address": ""
    },
    {
      "co_host": "Olubxnmi",
      "co_host_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "co_host_wallet_address": ""
    }
  ],
  "description": "",
  "home_page_show_participate": [
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1481661390049976323/ET6nfC1l_normal.jpg",
      "participate_name": "EmekaDinkpa",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1458216078039977989/41pJ4qhA_normal.jpg",
      "participate_name": "PlayoffP_",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1561442464187252736/XnAyBSZo_normal.jpg",
      "participate_name": "Monsiuer_T",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1540803788717449216/psqEjcT5_normal.jpg",
      "participate_name": "Olubxnmi",
      "participate_wallet_address": ""
    },
    {
      "participate_avatar": "https://pbs.twimg.com/profile_images/1192814495636348928/mQBv7aNI_normal.jpg",
      "participate_name": "dbenz_man",
      "participate_wallet_address": ""
    }
  ],
  "host": "BinanceAfrica",
  "host_avatar": "https://pbs.twimg.com/profile_images/1480341292877959169/5AgZD9Gr_normal.jpg",
  "host_wallet_address": "",
  "location": "aaa",
  "name": "How To Buy Crypto With NGN Using Cashlink",
  "room_id": "!WJjoOHqhOoizFoNNle:localhost:8080",
  "source": "Twitter",
  "start_time": 1668769242000,
  "tag_icon": "xxx",
  "tag_text": "xxx",
  "title": "How To Buy Crypto With NGN Using Cashlink",
  "url": "https://beta.soshow.io/#/?space=1ypKddykkbgKW"
}

Responses

Status Description
200 update ama activity successfully

API8. Delete AMA activity in Home Page

DELETE /_api/client/r0/server/homePageShow/{id}

delete home page show by id
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
id string The id of the activity

Responses

Status Description
200 delete home page show activity successfully.

API9. Thirty party recommend squad to SendingMe

POST /_api/client/r0/server/recommend_squad_explore/new

the thirty party recommend room_id to Sending Me, then you can search the squad in sendingMe App
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Request body example

{
  "room_id": "!zeGzqNBZqQDYtjJYRs:localhost:8080"
}

Responses

Status Description
200 recommend squad successfully.

API10. Get squad url from squad id

GET /_api/client/r0/get-room-url/{room_id}

get squad url by squad id
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
room_id string Required: The squad id

Responses

Status Description
200 get squad url successfully.

200 response

{
  "url": "http://localhost:8080/#/room/!WJjoOHqhOoizFoNNle:localhost:8080"
}

API11. Put room in squad

PUT /_api/client/r0/server/rooms/{squad_id}/state/{event_type}/{room_id}

the room put in owner home default, put room in squad
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
event_type string Required: the message of the event, this is “m.space.child”
room_id string Required: the put to squad room id
squad_id string Required: The squad id

Request body

Name Type Description
auto_join boolean Optional (default false)
suggested boolean Optional (default false) flag to denote whether the child is “suggested” or of interest to members of the space. This is primarily intended as a rendering hint for clients to display the room differently, such as eagerly rendering them in the room list.

Request body example

{
  "auto_join": false,
  "suggested": false
}

Responses

Status Description
200 put room in squad successfully.

200 response

{
  "event_id": "$-4PiIsIpnRwS_epcdFBkx3mcElRqTPIaE-ie6JUDo6E"
}

API12. Transfer owner to another member in room

POST /_api/client/r0/server/rooms/{room_id}/transfer-owner

Transfer owner to another person.

curl --location 'http://{homeserver}/_api/client/r0/server/rooms/{room_id}/transfer-owner' \
--header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
--header 'Content-Type: application/json' \
--data-raw '{"owner":"@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080"}'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
owner string Required: A room Id.

Request body example

{
  "owner": "@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080"
}

Responses

Status Description
200 transfer owner to another successfully
400 The server access token is not invalid
403 The new owner you set is not in the room
405 The room is not a squad, only squad can transfer owner to another member
412 The new owner you set is not in the room
413 The owner you set is yourself

200 response

Name Type Description
event_id string Required: A event id 
{
  "event_id": "$qzDGfGODhlQuvYXZEdTvHURvDTHCBACy"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "Invalid param: server_access_token"
}

405 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_Ａ_SQUAD",
  "error": "NOT_A_SQUAD: the room id is not a squad"
}

412 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "UNAUTHORIZED: you are not owner of the room"
}

413 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "Invalid param: No need to set the owner to yourself"
}

API13. Set role to another member

POST /_api/client/r0/server/{room_id}/set-role

Set role to another member in squad or rooms, You can only set role below you. If you set role to one squad, the public room in the squad has the same permission with the squad. The member user id and role value, The role value must be 0 or 50 or 100. The default role is 0; the moderator role is 50; the admin role is 100.

curl --location '{homeserver}/_api/client/r0/server/rooms/{room_id}/set-role' \
--header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
--header 'Content-Type: application/json' \
--data-raw '{"@0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6:localhost:8080":50}'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Request body example

{
  "@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080": 100
}

Responses

Status Description
200 Set role to another member successfully
400 The server access token is not invalid
403 You don’t have permission to remove ops level equal to your own
405 You are not in the room
407 The user is not in the room
410 The permission value must 0,50,100
413 You can only set one member at a time

200 response

Name Type Description
event_id string Required: A event id 
{
  "event_id": "$qzDGfGODhlQuvYXZEdTvHURvDTHCBACy"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: server_access_token"
}

403 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_FORBIDDEN",
  "error": "You don't have permission to remove ops level equal to your own"
}

405 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: You are not in the room"
}

407 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: The user is not in the room"
}

410 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "M_INVALID_PARAM: The permission value must 0,50,100"
}

413 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "M_INVALID_PARAM: You can only set one member at a time"
}

API14. Search AMA activity by user id

GET /_api/client/r0/server/ama_activity/search_by_user_id/{user_id}

search ama activity by user id. the curl example.

  curl --location 'http://localhost:8080/_api/client/r0/server/ama_activity/search_by_user_id/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080' \
  --header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token returned by /bind-server-client api
path parameters
Name Type Description
user_id Required: the user id in SendingMe App

Responses

Status Description
200 search ama activity by user id successfully
403 Invalid param: server_access_token

200 response

{
  "ama_activity_list": [
    {
      "create_time_ms": 1679991278877,
      "description": "3243454657568767876867876765",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "MJCvykdsnarOMqXIPiUJWKSBNjTZfGIV",
      "participant_count": 0,
      "room_id": "!VWWINVsAdeGWqaAjlv:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "ended",
      "title": "create ama test",
      "topic": "",
      "users": []
    },
    {
      "create_time_ms": 1680494441665,
      "description": "3243454657568767876867876765",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm",
      "participant_count": 0,
      "room_id": "!krJjdoAOFtySAXGafZ:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "live",
      "title": "create ama test2",
      "topic": "",
      "users": [
        {
          "ama_activity_id": "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm",
          "id": "fwGzQNRJjDLwvKCPGtLRMPgwBtNMahCn",
          "participate_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
          "participate_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "connor zhang",
          "status": "offline"
        }
      ]
    },
    {
      "create_time_ms": 1682339945561,
      "description": "Web3 world start",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
      "participant_count": 2,
      "room_id": "!zUzHGkrDKbsyhstUda:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "scheduled",
      "title": "create ama test2",
      "topic": "",
      "users": [
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "bnEkqSAmrGxGKTtgIWXmrxbsVZWokiyQ",
          "participate_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
          "participate_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "connor zhang",
          "status": "offline"
        },
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "dDDMxZHBvRgqdozZGfFjyweMzSTFqedU",
          "participate_address": "0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec",
          "participate_avatar": "https://static.sending.me/beam/120/@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "yhzhang-test",
          "status": "line"
        },
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "HRJLcvBPZIPEkasROkBXwCngXcSkLhGB",
          "participate_address": "0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6",
          "participate_avatar": "https://static.sending.me/beam/120/@0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "yhzhang-test",
          "status": "line"
        }
      ]
    }
  ]
}

API15. Search AMA activity by AMA id

GET /_api/client/r0/server/ama_activity/search_by_ama_id/{ama_id}

search ama activity by ama id. the curl example.

  curl --location 'http://localhost:8080/_api/client/r0/server/ama_activity/search_by_ama_id/hErTRaUeZNxQAWOYNYWmcnhTJFVwJyEJ' \
  --header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token returned by /bind-server-client api
path parameters
Name Type Description
ama_id Required: the AMA activity id created in SendingMe App

Responses

Status Description
200 search ama activity by user id successfully
403 Invalid param: server_access_token

200 response

{
  "ama_activity_list": [
    {
      "create_time_ms": 1679573269593,
      "description": "sdsdsdssssssssssssssssssssssss",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "hErTRaUeZNxQAWOYNYWmcnhTJFVwJyEJ",
      "participant_count": 1,
      "room_id": "!VWWINVsAdeGWqaAjlv:localhost:8080",
      "start_time_ms": 124546565675,
      "state": "scheduled",
      "title": "Web3 2049",
      "topic": "",
      "users": [
        {
          "ama_activity_id": "hErTRaUeZNxQAWOYNYWmcnhTJFVwJyEJ",
          "id": "cPpSMmOvabaugAonlCFwjCwWQdHeWWTP",
          "participate_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
          "participate_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "connor zhang",
          "status": "line"
        }
      ]
    }
  ]
}

API16. Search AMA activity by AMA id list

POST /_api/client/r0/server/ama_activity/search_by_ama_id_list

search ama activity by ama activity id list. the curl example.

  curl --location 'http://{homeserver}/_api/client/r0/server/ama_activity/search_by_ama_id_list' \
    --header 'Authorization: Bearer {server_access_token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "ama_id_list":[
        "MJCvykdsnarOMqXIPiUJWKSBNjTZfGIV",
        "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm"
      ]
    }'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token returned by /bind-server-client api

Request body

Request body example

{
  "ama_id_list": [
    "MJCvykdsnarOMqXIPiUJWKSBNjTZfGIV",
    "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm"
  ]
}

Responses

Status Description
200 search ama activity by ama activity id list successfully
400 Invalid param: server_access_token
403 Invalid param: ama_id_list

200 response

{
  "ama_activity_list": [
    {
      "create_time_ms": 1679991278877,
      "description": "3243454657568767876867876765",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "MJCvykdsnarOMqXIPiUJWKSBNjTZfGIV",
      "participant_count": 0,
      "room_id": "!VWWINVsAdeGWqaAjlv:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "ended",
      "title": "create ama test",
      "topic": "",
      "users": []
    },
    {
      "create_time_ms": 1680494441665,
      "description": "3243454657568767876867876765",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm",
      "participant_count": 0,
      "room_id": "!krJjdoAOFtySAXGafZ:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "live",
      "title": "create ama test2",
      "topic": "",
      "users": [
        {
          "ama_activity_id": "ziRfUnvqpeqmHwIHmCPDExcfCihoRWAm",
          "id": "fwGzQNRJjDLwvKCPGtLRMPgwBtNMahCn",
          "participate_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
          "participate_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "connor zhang",
          "status": "offline"
        }
      ]
    },
    {
      "create_time_ms": 1682339945561,
      "description": "Web3 world start",
      "host_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
      "host_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
      "host_name": "connor zhang",
      "id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
      "participant_count": 2,
      "room_id": "!zUzHGkrDKbsyhstUda:localhost:8080",
      "start_time_ms": 1679986763353,
      "state": "scheduled",
      "title": "create ama test2",
      "topic": "",
      "users": [
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "bnEkqSAmrGxGKTtgIWXmrxbsVZWokiyQ",
          "participate_address": "0x00bb58c7d86ff59db312e2e676fda8820502f697",
          "participate_avatar": "https://static.sending.me/beam/120/@0x00bb58c7d86ff59db312e2e676fda8820502f697:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "connor zhang",
          "status": "offline"
        },
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "dDDMxZHBvRgqdozZGfFjyweMzSTFqedU",
          "participate_address": "0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec",
          "participate_avatar": "https://static.sending.me/beam/120/@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "yhzhang-test",
          "status": "line"
        },
        {
          "ama_activity_id": "ugbRhxDkEEySnZhhFWyLkBywUDBYZfLA",
          "id": "HRJLcvBPZIPEkasROkBXwCngXcSkLhGB",
          "participate_address": "0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6",
          "participate_avatar": "https://static.sending.me/beam/120/@0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6:localhost:8080?colors=02D69E,BC39FF,2C96FF,FF9A1C,106EEC\u0026\u0026square=true",
          "participate_name": "yhzhang-test",
          "status": "line"
        }
      ]
    }
  ]
}

API17. Get user contacts by wallet address

GET /_api/client/r0/server/contacts

Get contact information based on wallet_address (paging).
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string Required: The server access token
query parameters
Name Type Description
limit integer Quantity per page (default - 100)
offset integer Paging shift (default - 0)
wallet_address string the wallet address for user

Responses

Status Description
200 return contact list.

200 response

{
  "contacts": [
    {
      "avatar_url": "https://hs-alpha.sending.me/_api/media/r0/thumbnail/hs-alpha.sending.me/0x5a4ffe4896673da1c95e165f24030640f7016771_17?width=48\u0026height=48",
      "displayname": "6081.bnb",
      "user_id": "@0x0f83535ba873602491d261538173a064b80ee266:hs-alpha.sending.me",
      "wallet_address": "0x0F83535BA873602491D261538173A064B80eE266"
    },
    {
      "avatar_url": "https://hs-alpha.sending.me/_api/media/r0/thumbnail/hs-alpha.sending.me/0x1a223494ed356c2990803ec5d904389e8feec1a2_3186?width=48\u0026height=48",
      "displayname": "luna❤.eth",
      "user_id": "@0xe6d0dd18c6c3a9af8c2fab57d6e6a38e29d513cc:hs-alpha.sending.me",
      "wallet_address": "0xE6D0Dd18C6C3a9Af8C2FaB57d6e6A38E29d513cC"
    }
  ],
  "total": 100
}

Third-party Server API [v2]

Descriptions for accessing the IM API from the third-party server [v2]

Server create squad

POST /_api/client/r0/server/v2/createRoom

[v2]Create a new squad.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
creation_content CreationContent Required: Type “m.space” represents a squad. If no “creation_content” in parameters, ｂy default the room will be created
initial_state [StateEvent] Required:

A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

Takes precedence over events set by preset, but gets overridden by name and topic keys.
name string Required: If this is included, an m.room.name event will be sent into the room to indicate the name of the room. See Room Events for more information on m.room.name.
room_alias_name string Required:

The desired room alias local part. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the same homeserver which created the room. For example, if this was set to “foo” and sent to the homeserver “example.com” the complete room alias would be #foo:example.com.

The complete room alias will become the canonical alias for the room and an m.room.canonical_alias event will be sent into the room.
StateEvent
Name Type Description
content object Required: The content of the event.
state_key string The state_key of the state event. Defaults to an empty string.
type string Required: The type of event to send. “m.room.avatar” represents a avatar of the squad you creates

Request body example

{
  "creation_content": {
    "type": "m.space"
  },
  "initial_state": [
    {
      "content": {
        "url": "mxc://localhost:8080/LyZyBcvugNtgJqHIRZMNyqdj"
      },
      "type": "m.room.avatar"
    }
  ],
  "name": "yhzhang-test1",
  "room_alias_name": "yhzhang-test111"
}

Responses

Status Description
200 Information about the newly created room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response

Name Type Description
room_id string Required: The created room’s ID. 
{
  "room_alias": "#yhzhang-test111:localhost:8080",
  "room_id": "!rbrwRgtDMyheefNQch:localhost:8080"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

Server create room

POST /_api/client/r0/server/v2/createRoom

[v2]Create a room that belongs to a squad.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
initial_state [StateEvent] Required:

A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

Takes precedence over events set by preset, but gets overridden by name and topic keys.

The type of event to send.
“m.room.join_rules”
A room may have one of the following designations:

public – anyone can join the room without any prior action.
invite – a user must first receive an invite from someone already in the room in order to join.
knock – a user can request an invite to the room. They can be allowed (invited) or denied (kicked/banned) access. Otherwise, users need to be invited in. Only available in rooms which support knocking.
restricted – anyone able to satisfy at least one of the allow conditions is able to join the room without prior action. Otherwise, an invite is required. Only available in rooms which support the join rule.
knock_restricted – a user can request an invite using the same functions offered by the knock join rule, or can attempt to join having satisfied an allow condition per the restricted join rule. Only available in rooms which support the join rule.
private – reserved without implementation. No significant meaning.

“m.space.parents”
The parent squad ID.
canonical: boolean
Optional (default false) flag to denote this parent is the primary parent for the room. When multiple canonical parents are found, the lowest parent when ordering by room ID lexicographically by Unicode code-points should be used.
name string Required: The room name
StateEvent
Name Type Description
content object Required: The content of the event.
state_key string The state_key of the state event. Defaults to an empty string.
type string Required: The type of event to send.

Request body example

{
  "initial_state": [
    {
      "content": {
        "join_rule": "public"
      },
      "type": "m.room.join_rules"
    },
    {
      "content": {
        "canonical": true,
        "via": [
          "localhost:8080"
        ]
      },
      "state_key": "!bOTqPHjJBTVFBQBHdQ:localhost:8080",
      "type": "m.space.parent"
    }
  ],
  "name": "a3"
}

Responses

Status Description
200 Information about the newly created room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response

Name Type Description
room_id string Required: The created room’s ID. 
{
  "room_id": "!sefiuhWgwghwWgh:example.com"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

Send room message

PUT /_api/client/r0/server/v2/send/m.room.message

[v2]post message to room.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string Required: The server access token

Request body

Name Type Description
body string The textual representation of this message.
msgtype string Required: The type of message, e.g. m.image, m.text
room_id string A room Id.

Request body example

{
  "content": {
    "body": "https://app-alpha.sending.me",
    "msgtype": "m.text"
  },
  "room_id": "!tuKKVwEACyWeqdBRwN:localhost:8080"
}

Responses

Status Description
200 An ID for the sent event.

200 response

Name Type Description
event_id string Required: A unique identifier for the event. 
{
  "event_id": "!sefiuhWgwghwWgh:example.com"
}

Transfer owner to another member in room

POST /_api/client/r0/server/v2/rooms/{room_id}/transfer-owner

[v2]Transfer owner to another person.

curl --location 'http://{homeserver}/_api/client/r0/server/rooms/{room_id}/transfer-owner' \
--header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
--header 'Content-Type: application/json' \
--data-raw '{"owner":"@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080"}'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Name Type Description
owner string Required: A room Id.

Request body example

{
  "owner": "@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080"
}

Responses

Status Description
200 transfer owner to another successfully
400 The server access token is not invalid
403 The new owner you set is not in the room
405 The room is not a squad, only squad can transfer owner to another member
412 The new owner you set is not in the room
413 The owner you set is yourself

200 response

Name Type Description
event_id string Required: A event id 
{
  "event_id": "$qzDGfGODhlQuvYXZEdTvHURvDTHCBACy"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "Invalid param: server_access_token"
}

405 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_Ａ_SQUAD",
  "error": "NOT_A_SQUAD: the room id is not a squad"
}

412 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "UNAUTHORIZED: you are not owner of the room"
}

413 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "Invalid param: No need to set the owner to yourself"
}

Set role to another member

POST /_api/client/r0/server/v2/{room_id}/set-role

[v2] Set role to another member in squad or rooms, You can only set role below you. If you set role to one squad, the public room in the squad has the same permission with the squad. The member user id and role value, The role value must be 0 or 50 or 100. The default role is 0; the moderator role is 50; the admin role is 100.

curl --location '{homeserver}/_api/client/r0/server/rooms/{room_id}/set-role' \
--header 'Authorization: Bearer AChJeZHjYBJODoNOLzraQBxLZedTHCHh' \
--header 'Content-Type: application/json' \
--data-raw '{"@0x6c33126d15f86d37cedc9f5a5f069dcd46b7c7e6:localhost:8080":50}'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Request body

Request body example

{
  "@0xd1bfe1aa011255fc45f15929c2aa3a652cce38ec:localhost:8080": 100
}

Responses

Status Description
200 Set role to another member successfully
400 The server access token is not invalid
403 You don’t have permission to remove ops level equal to your own
405 You are not in the room
407 The user is not in the room
410 The permission value must 0,50,100
413 You can only set one member at a time

200 response

Name Type Description
event_id string Required: A event id 
{
  "event_id": "$qzDGfGODhlQuvYXZEdTvHURvDTHCBACy"
}

400 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: server_access_token"
}

403 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_FORBIDDEN",
  "error": "You don't have permission to remove ops level equal to your own"
}

405 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: You are not in the room"
}

407 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_UNAUTHORIZED",
  "error": "M_UNAUTHORIZED: The user is not in the room"
}

410 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "M_INVALID_PARAM: The permission value must 0,50,100"
}

413 response

Error
Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_INVALID_PARAM",
  "error": "M_INVALID_PARAM: You can only set one member at a time"
}

Get squad url from squad id

GET /_api/client/r0/server/v2/get-room-url/{room_id}

[v2]get squad url by squad id
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
room_id string Required: The squad id

Responses

Status Description
200 get squad url successfully.

200 response

{
  "url": "http://localhost:8080/#/room/!WJjoOHqhOoizFoNNle:localhost:8080"
}

Get members by room/squad id

GET /_api/client/r0/server/v2/get_room_members/{room_id}

get room/squad members v2
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
room_id string Required: The squad id

Responses

Status Description
200 get squad members successfully.

200 response

{
  "members": [
    {
      "avatar_url": "",
      "display_name": "0x49ea36522bd6ffe3330b6803cc3b4efc1f434a9b",
      "user_id": "@sdn_49ea36522bd6ffe3330b6803cc3b4efc1f434a9b:49ea36522bd6ffe3330b6803cc3b4efc1f434a9b",
      "wallet_address": "0x49ea36522bd6ffe3330b6803cc3b4efc1f434a9b"
    }
  ],
  "owner": "@sdn_49ea36522bd6ffe3330b6803cc3b4efc1f434a9b:49ea36522bd6ffe3330b6803cc3b4efc1f434a9b",
  "total": 1
}

Get user profile

GET /_api/client/r0/server/v2/get_user_info

get user profile
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token

Responses

Status Description
200 get user profile successfully.

200 response

{
  "avatar_url": "https://static.sending.me/beam/70/@sdn_7c2fca2e56981de8346b9419a1c3a7a70d0012ca:7c2fca2e56981de8346b9419a1c3a7a70d0012ca?square=true",
  "display_name": "terryyang-03",
  "user_id": "@sdn_7c2fca2e56981de8346b9419a1c3a7a70d0012ca:7c2fca2e56981de8346b9419a1c3a7a70d0012ca",
  "wallet_address": "0x7c2FcA2E56981dE8346B9419A1c3a7A70D0012CA"
}

Put room in squad

PUT /_api/client/r0/server/v2/rooms/{squad_id}/state/m.space.child/{room_id}

the room put in owner home default, put room in squad
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string The server access token
path parameters
Name Type Description
room_id string Required: the put to squad room id
squad_id string Required: The squad id

Request body

Name Type Description
auto_join boolean Optional (default false)
suggested boolean Optional (default false) flag to denote whether the child is “suggested” or of interest to members of the space. This is primarily intended as a rendering hint for clients to display the room differently, such as eagerly rendering them in the room list.

Request body example

{
  "auto_join": false,
  "suggested": false
}

Responses

Status Description
200 put room in squad successfully.

200 response

{
  "event_id": "$-4PiIsIpnRwS_epcdFBkx3mcElRqTPIaE-ie6JUDo6E"
}

Get room base info in squad

GET /_api/client/r0/server/v2/rooms_in_squad/{room_id}

Get the list of rooms. the curl example

curl --location '{homeserver}/_api/client/r0/server/v2/rooms_in_squad/!JHwV62u5n8Y6oaLa-@sdn_3fbd97eaa8c435ba03d1134252eac6eecd3f794b:3fbd97eaa8c435ba03d1134252eac6eecd3f794b' \
--header 'Authorization: Bearer WKQJcBOsAooyUAEYMvyKfJcPiaEBEPwh'

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Authorization string Required: The server access token
path parameters
Name Type Description
room_id string Required: the squad id

Responses

Status Description
200 A joined squad list

200 response

[
  {
    "name": "aaa",
    "room_id": "!bu3aLR1jl5DbOoc0-@sdn_fcaa0c482daea5da89ca31d9b81d4b433866b6b1:fcaa0c482daea5da89ca31d9b81d4b433866b6b1"
  },
  {
    "name": "General",
    "room_id": "!npiJFnSyR0dDoMra-@sdn_fcaa0c482daea5da89ca31d9b81d4b433866b6b1:fcaa0c482daea5da89ca31d9b81d4b433866b6b1"
  }
]