Talkee API

How to specify a site

Some APIs require you to specify a site, for example, GET /comments need to know which site you want to get comments from. There are two ways to do that:

You can specify a site by setting the X-TALKEE-SITE-ID or X-TALKEE-SITE-SLUG header.
You can specify a site by setting the site_id or slug query parameter.

Both ways are valid, but you can only use one of them at a time. If you specify a site by both ways, the header will be used.

POST /auth/login

This API is used to login to Talkee.

Talkee's authentication is slightly different from other pando protocols. It uses own JWT token to identify users.

To get the JWT token, there are three ways:

Login with Mixin access token: You need to exchange Mixin's access_token to Talkee's access_token. Assign mixin_token to method and mixin's access_token mentioned in the Authorization to mixin_access_token in the request body.
Login with Ethereum: You need to sign an EIP-4361 messages to exchange for Talkee's access_token. Assign mvm to method, put the signed message to signed_message and the signature to signature in the request body.
Please read this section to learn how to generate the signed message and signature.

After you get the access_token, save the access_token in the response to access other authenticated APIs.

Params

Name	Type	In	Required	Description
method	string	json	true	the login method, can be "mixin_token" or "mvm"
mixin_token	string	json	false	the access token of mixin, should be signed for `/me` or a regular Mixin OAuth token. Only required when `method` is "mixin_token"
signature	string	json	false	the signature of the message, generated by EIP-4361 process. Only required when `method` is "mvm"
signed_message	string	json	false	the signed message. It is a JSON object contains all required fields of EIP-4361. Only required when `method` is "mvm"
lang	string	json	false	the language of user, 2 letters, like "en", "ja" etc.

TIP

Note that the mixin_access_token is same as the access_token in the Authorization.

Response

json

{
  "ts": 1675582938650,
  "data": {
    "access_token": "eyJhbG....lBM",
    "user": {
      "id": 1,
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    }
  }
}

Get site info

GET /sites/:site_id

This API is used to get site info.

Params

Name	Type	In	Required	Description
site_id	number	url	true	the site's id

Response

json

{
  "ts": 1675583895807,
  "data": {
    "id": 1,
    "user_id": 1,
    "origins": [ "https://...", "https://..." ],
    "name": "A Test Site",
    "use_arweave": false,
    "reward_strategy": 0,
    "created_at": "2022-02-05T16:11:16.420872+09:00",
    "updated_at": "2022-02-05T16:11:16.420872+09:00"
  }
}

Create a comment

AUTHORIZATION REQUIRED

POST /comments

This API is used to create new comments.

Params

Name	Type	In	Required	Description
X-TALKEE-SITE-ID	string	header	true	site's id
X-TALKEE-SITE-SLUG	string	header	true	the slug of site
content	string	json	true	the text content.

Response

json

{
  "ts": 1675583187295,
  "data": {
    "id": 15,
    "user_id": "4",
    "site_id": 1,
    "slug": "/posts/11",
    "favor_count": 3,
    "reply_count": 2,
    "arweave_tx_hash": "...",
    "content": "Hello!",
    "created_at": "2023-02-05T16:11:58.175076+09:00",
    "updated_at": "2023-02-05T16:11:58.175076+09:00",
    "creator": {
      "id": "4",
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    },
    "rewards": [
      { /*...*/ },
      { /*...*/ }
    ]
  }
}

Get comments

GET /comments?limit=:limit&offset=:offset&order_by=:order_by

This API is used to get comments.

Params

Name	Type	In	Required	Description
X-TALKEE-SITE-ID	string	header	true	site's id
X-TALKEE-SITE-SLUG	string	header	true	the slug of site
limit	number	url	false	the limitation of items in response
offset	number	url	false	the offset to start from
order_by	string	url	false	the order of items in response, can be "created_at", "created_at_asc" or "favor_count"

Response

json

{
  "ts": 1675583187295,
  "data": {
    "comments": [{
      "id": 15,
      "user_id": "4",
      "site_id": 1,
      "slug": "/posts/11",
      "favor_count": 3,
      "reply_count": 2,
      "arweave_tx_hash": "...",
      "content": "Hello!",
      "created_at": "2023-02-05T16:11:58.175076+09:00",
      "updated_at": "2023-02-05T16:11:58.175076+09:00",
      "creator": {
        "id": "4",
        "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "mixin_identity_number": "1234456",
        "full_name": "John Wick",
        "avatar_url": "https://mixin-images.zeromesh.net/...",
        "created_at": "2022-02-05T16:11:16.420872+09:00"
      },
      "rewards": [
        { /*...*/ },
        { /*...*/ }
      ]
    },
    // ...
    ],
    "total": 128,
  }
}

Get a comment

GET /comments/:comment_id

This API is used to get a specific comment.

Params

Name	Type	In	Required	Description
comment_id	number	url	true	the comment's id

Response

json

{
  "ts": 1675583187295,
  "data": {
    "id": 15,
    "user_id": "4",
    "site_id": 1,
    "slug": "/posts/11",
    "favor_count": 3,
    "reply_count": 2,
    "arweave_tx_hash": "...",
    "content": "Hello!",
    "created_at": "2023-02-05T16:11:58.175076+09:00",
    "updated_at": "2023-02-05T16:11:58.175076+09:00",
    "creator": {
      "id": "4",
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    },
    "rewards": [
      { /*...*/ },
      { /*...*/ }
    ]
  }
}

Favorite a comment

AUTHORIZATION REQUIRED

PUT /comments/:comment_id/fav

This API is used to favorite a comment specified in the ID parameter as the authenticating user. Returns the favorite comment when successful.

Params

Name	Type	In	Required	Description
X-TALKEE-SITE-ID	string	header	true	site's id
X-TALKEE-SITE-SLUG	string	header	true	the slug of site
comment_id	number	url	true	the comment's id

Response

json

{
  "ts": 1675583187295,
  "data": {
    "id": 15,
    "user_id": "4",
    "site_id": 1,
    "slug": "/posts/11",
    "favor_count": 3,
    "reply_count": 2,
    "arweave_tx_hash": "...",
    "content": "Hello!",
    "created_at": "2023-02-05T16:11:58.175076+09:00",
    "updated_at": "2023-02-05T16:11:58.175076+09:00",
    "creator": {
      "id": "4",
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    },
    "rewards": [
      { /*...*/ },
      { /*...*/ }
    ]
  }
}

Unfavorite a comment

AUTHORIZATION REQUIRED

PUT /comments/:comment_id/unfav

This API is used to unfavorite a comment specified in the ID parameter as the authenticating user. Returns the unfavorite comment when successful.

Params

Name	Type	In	Required	Description
X-TALKEE-SITE-ID	string	header	true	site's id
X-TALKEE-SITE-SLUG	string	header	true	the slug of site
comment_id	number	url	true	the comment's id

Response

json

{
  "ts": 1675583187295,
  "data": {
    "id": 15,
    "user_id": "4",
    "site_id": 1,
    "slug": "/posts/11",
    "favor_count": 3,
    "reply_count": 2,
    "arweave_tx_hash": "...",
    "content": "Hello!",
    "created_at": "2023-02-05T16:11:58.175076+09:00",
    "updated_at": "2023-02-05T16:11:58.175076+09:00",
    "creator": {
      "id": "4",
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    },
    "rewards": [
      { /*...*/ },
      { /*...*/ }
    ]
  }
}

Create a reply

AUTHORIZATION REQUIRED

POST /comments/:comment_id/replies

This API is used to create new reply for a specific comment.

Params

Name	Type	In	Required	Description
comment_id	number	url	true	the comment's id
content	string	json	true	the text content.

Response

json

{
  "ts": 1675583738297,
  "data": {
    "id": 17,
    "user_id": "3",
    "comment_id": "4",
    "content": "A reply",
    "created_at": "2023-02-05T16:55:38.266176+09:00",
    "updated_at": "2023-02-05T16:55:38.266176+09:00",
    "creator": {
      "id": "4",
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    }
  }
}

Get replies

GET /comments/:comment_id/replies?limit=:limit&offset=:offset&

This API is used to create new reply for a specific comment.

Params

Name	Type	In	Required	Description
limit	number	url	false	the limitation of items in response
offset	number	url	false	the offset to start from
comment_id	number	url	true	the comment's id
content	string	json	true	the text content.

Response

json

{
  "ts": 1675583187295,
  "data": {
    "replies": [{
      "id": 17,
      "user_id": "3",
      "comment_id": "4",
      "content": "A reply",
      "created_at": "2023-02-05T16:55:38.266176+09:00",
      "updated_at": "2023-02-05T16:55:38.266176+09:00",
      "creator": {
        "id": "4",
        "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "mixin_identity_number": "1234456",
        "full_name": "John Wick",
        "avatar_url": "https://mixin-images.zeromesh.net/...",
        "created_at": "2022-02-05T16:11:16.420872+09:00"
      }
    }
    // ...
    ],
    "total": 128,
  }
}

Get a user

GET /users/:user_id

This API is used to get a user info.

Params

Name	Type	In	Required	Description
user_id	number	url	true	the user's id

Response

json

{
  "ts": 1675584720934,
  "data": {
    "id": 1,
    "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "mixin_identity_number": "1234456",
    "full_name": "John Wick",
    "avatar_url": "https://mixin-images.zeromesh.net/...",
    "created_at": "2022-02-05T16:11:16.420872+09:00"
  }
}

Get me

AUTHORIZATION REQUIRED

GET /me

This API is used to get my info.

Response

json

{
  "ts": 1675584720934,
  "data": {
    "id": 1,
    "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "mixin_identity_number": "1234456",
    "full_name": "John Wick",
    "avatar_url": "https://mixin-images.zeromesh.net/...",
    "created_at": "2022-02-05T16:11:16.420872+09:00"
  }
}

DRAFT PROPOSAL

The following section is a draft proposal, it's not finalized yet.

Create an airdrop

AUTHORIZATION REQUIRED

POST /airdrops

Call the API to create an airdrop for multiple comments, a slug or a user.

Params

Name	Type	In	Required	Description
airdrop_type	string	json	true	the airdrop type. support "comments", "comment", "user", "slug"
site_id	number	json	false	the site's id. It's required for "slug" and "comments" airdrop type.
slug	string	json	false	the site's slug. It's required for "slug" and "comments" airdrop type.
opponent_id	number	json	false	opponent's id. It's required for "user" and "comment" airdrop type. For "user" airdrop type, it should be the user's id. For "comment" airdrop type, it should be the comment's id.
strategy_name	string	json	false	the airdrop strategy name, support "topn" or "avg". It's required for "comments" airdrop type.
strategy_params	json	json	false	the airdrop strategy params. It's required for "comments" airdrop type. For "topn", it should be a JSON object contains "n" field, like {"n": 3}.
asset_id	UUID	json	true	the asset id to airdrop
amount	string	json	true	how much to airdrop. The precision should be 8, like "1.23456789"
memo	string	json	true	the memo of the airdrop transaction
redirect_url	string	json	true	the redirect url after airdrop

There are four types of airdrops:

Airdrop to a specific user: airdrop_type is set to user. opponent_id is set to the user ID.
Airdrop to a specific slug: airdrop_type is set to slug. site_id and slug should be set.
Air drop to a specific comment: airdrop_type is set to comment. opponent_id is set to the comment ID.
Airdrop to a set of comments: airdrop_type is set to comments. site_id and slug should be set. strategy_name and strategy_params should be set.

Response

json

{
  "ts": 1680674968664,
  "data": {
    "id": 13,
    "uuid": "c85d17c8-1e51-43da-b7c5-3a988bc61022",
    "user_id": 3,
    "site_id": 1,
    "slug": "ABC",
    "opponent_id": 0,
    "tip_type": "comments",
    "strategy_name": "topn",
    "strategy_params": {
        "n": 3
    },
    "asset_id": "c6d0c728-2624-429b-8e0d-d9d19b6592fa",
    "amount": "0.0000001",
    "memo": "test",
    "status": 0,
    "created_at": "2023-04-05T15:09:28.386937+09:00",
    "updated_at": "2023-04-05T15:09:28.386937+09:00",
    "deleted_at": null,
    "mixpay_code": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

To complete the airdrop payment, you need to redirect the user to following URL:

text

https://mixpay.me/code/:mixpay_code

in which :mixpay_code is the mixpay_code returned by the API.

Talkee API #

How to specify a site #

Login #

Response #

Get site info #

Response #

Create a comment #

Response #

Get comments #

Response #

Get a comment #

Response #

Response #

Favorite a comment #

Response #

Unfavorite a comment #

Response #

Create a reply #

Response #

Get replies #

Response #

Get a user #

Response #

Get me #

Response #

Create an airdrop #

Response #

Talkee API

How to specify a site

Login

Response

Get site info

Response

Create a comment

Response

Get comments

Response

Get a comment

Response

Response

Favorite a comment

Response

Unfavorite a comment

Response

Create a reply

Response

Get replies

Response

Get a user

Response

Get me

Response

Create an airdrop

Response