|
1 | 1 | # sendbird-nodejs
|
2 |
| -Thin wrapper around SendBird Server REST API |
3 |
| - |
4 |
| -# PLEASE NOTE THIS WORKS ON TOP OF `SENDBIRD V2.0` API - V3.0 WILL COME SOON |
| 2 | +Thin wrapper around SendBird's Platform API |
5 | 3 |
|
6 | 4 | ## Installation
|
7 |
| -`npm install sendbird-nodejs --save` |
| 5 | + npm install sendbird-nodejs --save |
| 6 | + |
| 7 | +or |
8 | 8 |
|
| 9 | + yarn add sendbird-nodejs |
9 | 10 |
|
10 | 11 | ## Usage
|
11 |
| -See [SendBird Documentation](https://docs.sendbird.com/v2/platform) for payload and response details. |
12 |
| -You don't need to pass the `auth` field on the payload, you provide it when creating a new instance of `SendBird` and it is attached to all requests. |
| 12 | +See [SendBird Documentation](https://docs.sendbird.com/platform) for payload and response details. |
| 13 | +You must provide your `API Token` when creating a new instance of `SendBird` and it will be attached to all requests. |
13 | 14 |
|
14 | 15 | ```javascript
|
15 | 16 | var SendBird = require('sendbird-nodejs');
|
16 |
| -var sb = new SendBird(config.sendBird.appToken); |
| 17 | +var sb = new SendBird(/* your sendbird api token here */); |
| 18 | +``` |
| 19 | + |
| 20 | +The `sb` instance we just created has an entry for each endpoint in the [SendBird Platform API](https://docs.sendbird.com/platform), it is an object with the endpoints methods. |
| 21 | +Note that all methods return a `Promise` as returned by [request-promise](https://github.com/request/request-promise). |
| 22 | + |
| 23 | + |
| 24 | +[sb.users](https://docs.sendbird.com/platform#user) |
| 25 | + |
| 26 | +[sb.openChannels](https://docs.sendbird.com/platform#open_channel) |
| 27 | +[sb.openChannels.messages](https://docs.sendbird.com/platform#messages) |
| 28 | +[sb.openChannels.metadata](https://docs.sendbird.com/platform#meta) |
| 29 | +[sb.openChannels.metacounter](https://docs.sendbird.com/platform#meta) |
| 30 | + |
| 31 | +[sb.groupChannels](https://docs.sendbird.com/platform#group_channel) |
| 32 | +[sb.groupChannels.messages](https://docs.sendbird.com/platform#messages) |
| 33 | +[sb.groupChannels.metadata](https://docs.sendbird.com/platform#meta) |
| 34 | +[sb.groupChannels.metacounter](https://docs.sendbird.com/platform#meta) |
| 35 | + |
| 36 | +##### Missing endpoints |
| 37 | + |
| 38 | +[sb.applications](https://docs.sendbird.com/platform#application) |
| 39 | +[sb.migration](https://docs.sendbird.com/platform#migration) |
| 40 | +[sb.bots](https://docs.sendbird.com/platform#bot_interface) |
| 41 | + |
| 42 | +### Example |
| 43 | + |
| 44 | +To create a user you would simply need to have something like this: |
| 45 | +```javascript |
| 46 | +const SendBird = require('sendbird-nodejs'); |
| 47 | +const sb = SendBird('<SOME API TOKEN>'); |
| 48 | + |
| 49 | +const payload = { |
| 50 | + "user_id": string, |
| 51 | + "nickname": string, |
| 52 | + "profile_url": string, |
| 53 | + "issue_access_token": boolean // (Optional) |
| 54 | +}; |
| 55 | +sb.users.create(payload) |
| 56 | + .then(function (response) { |
| 57 | + // do something with SendBird response |
| 58 | + // { |
| 59 | + // "user_id": string, |
| 60 | + // "nickname": string, |
| 61 | + // "profile_url": string, |
| 62 | + // "access_token": string, |
| 63 | + // "last_seen_at": long, |
| 64 | + // "is_online": boolean |
| 65 | + // } |
| 66 | + }); |
17 | 67 | ```
|
18 | 68 |
|
19 |
| -The `sb` instance we just created has a field for each endpoint in the [SendBird Server API](https://docs.sendbird.com/v2/platform#overview) that is an object with the endpoints methods. |
20 |
| -[sb.user](https://docs.sendbird.com/v2/platform#user) |
21 |
| -[sb.channel](https://docs.sendbird.com/v2/platform#open_chat) |
22 |
| -[sb.messaging](https://docs.sendbird.com/v2/platform#messaging) |
23 |
| -[sb.admin](https://docs.sendbird.com/v2/platform#admin) |
24 |
| -[sb.migration](https://docs.sendbird.com/v2/platform#migration) |
| 69 | +There are two different types of parameters the Platform API requires |
| 70 | + |
| 71 | +1. `url params` - you can see them in sendbird docs as `{some_param}` in the `URL` |
| 72 | +2. `payload/querystring params` - you can see them in the sendbird docs under the `request` section |
25 | 73 |
|
26 |
| -So, to create a user you would simply need to have something like this: |
| 74 | +We will treat the two types differently when calling the API. |
| 75 | +`url params` will be used as arguments for the API method you are calling. |
| 76 | +`payload/querystring params` will always a plain object and the last argument of the API method. |
| 77 | + |
| 78 | +This is how we would `send` a `message` to a `group channel` on behalf of some user using the API: [Send Message Docs](https://docs.sendbird.com/platform#messages_3_send) |
27 | 79 | ```javascript
|
28 |
| -var payload = { |
29 |
| - "id": string, // User ID |
30 |
| - "nickname": string, // User nickname |
31 |
| - "image_url": string, // User profile image URL |
32 |
| - "issue_access_token": boolean // Default is false. Use only if you want to create an access token for this user |
| 80 | +const SendBird = require('sendbird-nodejs'); |
| 81 | +const sb = SendBird('<SOME API TOKEN>'); |
| 82 | + |
| 83 | +const channelUrl = 'channel-url-from-sendbird'; |
| 84 | +const payload = { |
| 85 | + "message_type": "MESG", // Text message |
| 86 | + "user_id": string, // Sender user_id |
| 87 | + "message": string, // Empty string is not allowed. |
| 88 | + "data": string, // (Optional) Custom data |
| 89 | + "custom_type": string, // (Optional) default: '' |
| 90 | + "mark_as_read": boolean // (Optional) default: true |
33 | 91 | };
|
34 |
| -sb.user.create(payload) |
| 92 | +sb.groupChannels.messages.send(channelUrl, payload) |
35 | 93 | .then(function (response) {
|
36 |
| - // do something with SendBird response |
| 94 | + // do something with SendBird response |
| 95 | + // { |
| 96 | + // "message_id": long, |
| 97 | + // "type": "MESG", |
| 98 | + // "message": string, |
| 99 | + // "file": { |
| 100 | + // "name": string, |
| 101 | + // "url": string, |
| 102 | + // "type": string, |
| 103 | + // "size": int |
| 104 | + // }, |
| 105 | + // "data": string, |
| 106 | + // "channel_url": string, |
| 107 | + // "created_at": long, |
| 108 | + // "user": { |
| 109 | + // "nickname": string, |
| 110 | + // "user_id": string, |
| 111 | + // "profile_url": string |
| 112 | + // }, |
| 113 | + // "custom_type": string |
| 114 | + // } |
37 | 115 | });
|
38 | 116 | ```
|
| 117 | +In the [docs](https://docs.sendbird.com/platform#messages_3_send) we see the `URL` is `https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages` so the `channel_type` param will be set by using `sb.groupChannels` and the `channel_url` is the first argument we of `sb.groupChannels.message.send` |
39 | 118 |
|
40 | 119 |
|
41 | 120 | ## Contributing
|
|
0 commit comments