Deepvision Messenger API Library

Installing

To install library use:

npm install @deepvision/dvm.js

Initializing

Import library into your script file and create dvm instance with constructor.

import DVMApi from '<path_to_library>';

const dvm = new DVMApi({
    endpoint: 'api-enpoint',
    getAccessToken: () => 'token',
});

Getting updates

There is one way of receiving updates for your client — the updates.list method.

Update

This object represents an incoming update.

| Field | Type | Description | |-------|------|-------------| | id | String | The update‘s unique identifier. | | date | Integer | Date the update was caused in Unix time. | | type | String | Type of the update. Can be new-message, edit-message, delete-message, new-chat, delete-chat. |
| payload | Message or Chat | An instance of any kind - chat, message, etc. - that caused update. |

List Updates

Use this method to receive incoming updates. An Array of Update objects is returned.

const { updates, meta } = await dvm.updates.list({
    since,
    limit,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | since | Integer | Optional | Value of date of the last update you confirmed +1. By default, updates are returned starting with the earliest unconfirmed update. An update is considered confirmed as soon as dvm.updates.list method is called with a since higher than its date. All previous updates will forgotten. Defaults to 0. | | limit | Integer | Optional | Limits the number of updates to be returned. Values between 1—100 are accepted. Defaults to 10. |

Response:

| Parameter | Type | Description | |-----------|------|-------------| | updates | Array of Update | A list of Update objects. | | meta | PaginationMeta | Pagination info. |

Notes

1. In order to avoid getting duplicate updates, recalculate offset after each server response.

Available types

All types used in the Bot API responses are represented as JSON-objects.

Optional fields may be not returned when irrelevant.

Chat

| Field | Type | Description | |-------|------|-------------| | id | String | Unique identifier for this chat. | | type | String | Type of the chat. Can be private only. | | title | String | Optional Chat's name. | | members | Array of User | A list of chat's members. | | lastMessage | Message | Optional The last message was sent in this chat. |

Message

| Field | Type | Description | |-------|------|-------------| | id | String | Unique identifier for this message. | | from | User | Sender. | | date | Integer | Date the message was sent in Unix time. | | chat | Chat | Conversation the message belongs to. | | text | String | Text of the message. | | dateEdited | Integer | Date the message was last edited in Unix time. |

User

| Field | Type | Description | |-------|------|-------------| | id | String | Unique identifier for this user. It should consist of two parts and look like "origin:id", where origin can be "dvm" or other name of source messenger's database, such as telegram. | | firstName | String | Users's first name. | | lastName | String | Users's surname. |

User object can have more optional fields.

PaginationMeta

| Field | Type | Description | |-------|------|-------------| | total | Integer | Number of found items. | | limit | Integer | Limited number of retrieved items. Can be 1—100. | | offset | Integer | Sequential number of the first item among all found items. |

List of fields in PaginationMeta object can be different depending on the model.

Available methods

On successful call, a JSON-object containing the result will be returned.

Create Chat

Use this method to create new chat. On success, the created Chat is returned.

This method is available for registered users only.

const chat = await dvm.chats.create({
    type,
    members,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | type | String | Yes | Type of the chat. Can be private only. | | members | Array of String | Yes | List of user's unique identifiers. |

List Chats

Use this method to get list of chats of the current user and incomplete chats also, that can be joined.

This method is available for registered users only.

const { chats, meta } = await dvm.chats.list({
    offset,
    limit,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | offset | Integer | Optional | Sequential number of the first chat to be returned. Defaults to 0. | | limit | Integer | Optional | Limits the number of chats to be returned. Values between 1—100 are accepted. Defaults to 10. |

Response:

| Parameter | Type | Description | |-----------|------|-------------| | chats | Array of Chat | A list of Chat object. | | meta | PaginationMeta | Pagination info. |

Get Chat

Use this method to get info about chat. On success, a Chat object is returned

This method is available for registered users only.

const chat = await dvm.chats.withId(id).get();

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the chat. |

Delete Chat

Use this method to delete chat

This method is available for registered users only.

await dvm.chats.withId(id).delete();

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the chat. |

Join Chat

Use this method to add current user as a new member to a chat. Chats with incomplete type can be joined only. As soon as user join chat, the last one's type will be changed to private.

This method is available for registered users only.

await dvm.chats.withId(id).join();

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the chat. |

Create Chat Message

Use this method to send text messages. On success, the sent Message is returned.

This method is available for registered users only. This method is available for members of the chat only.

const message = await dvm.chats.withId(id).messages.create({
    text,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | text | String | Yes | Text of the message. |

List Chat Messages

Use this method to get list of Message objects for this chat

This method is available for registered users only.

const { messages, meta } = await dvm.chats.withId(id).messages.list({
    offset,
    limit,
    text,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the chat we get messages of. | | offset | Integer | Optional | Sequential number of the first message to be returned. Defaults to 0. | | limit | Integer | Optional | Limits the number of messages to be returned. Values between 1—100 are accepted. Defaults to 10. | | text | String | Optional | Filter. Messages contain the text will be returned. 0—100 characters. |

Response:

| Parameter | Type | Description | |-----------|------|-------------| | messages | Array of Message | A list of messages sorted from recent to old. | | meta | PaginationMeta | Pagination info. |

Get Message

Use this method to get message. On success, a Message object is returned.

This method is available for registered users only.

const chat = await dvm.messages.withId(id).get();

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the message. |

Edit Message

Use this method to edit message. On success, the new version of Message object is returned.

This method is available for registered users only.

const message = await dvm.messages.withId(id).edit({
    text,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the message. | | text | String | Yes | New text of the message. |

Delete Message

Use this method to delete message

This method is available for registered users only.

await dvm.messages.withId(id).delete()

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the message. |

Register User

Use this method to register user in DVM service. On success, the registered user is returned. If user with such id has already registered, throws error

const user = await dvm.users.register({
    id,
    firstName,
    lastName,
    ...
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the user. It should consist of two parts and look like "origin:id", where origin can be "dvm" or other name of source messenger's database, such as telegram. | | firstName | String | Yes | User's first name. | | lastName | String | Optional | User's surname. |

It is not finished list of properties. You can pass other user's info such as email, phone, avatar etc.

Get User

Use this method to get info about registered user. If user is not registered, method throws error

const chat = await dvm.users.withId(id).get();

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | String | Yes | Unique identifier for the user. It should consist of two parts and look like "origin:id", where origin can be "dvm" or other name of source messenger's database, such as telegram. |

List Users

Use this method to get list of registered users

const { users, meta } = await dvm.users.list({
    offset,
    limit,
});

Request:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | offset | Integer | Optional | Sequential number of the first user to be returned. Defaults to 0. | | limit | Integer | Optional | Limits the number of users to be returned. Values between 1—100 are accepted. Defaults to 10. |

Response:

| Parameter | Type | Description | |-----------|------|-------------| | users | Array of User | A list of User objects. | | meta | PaginationMeta | Pagination info. |

License

This project is licensed under the MIT License