Интеграция чата CarrotQuest в приложение Flutter

Доброго дня. В процессе разработки приложения на Flutter мы столкнулись с необходимостью интеграции чата CarrotQuest. Это позволит клиенту вести переговоры со своими пользователями в едином информационном потоке. Для интеграции будет использован специальный API, который предоставляет CarrotQuest.

Несмотря на подробное описание, некоторые шаги могут показаться неочевидными. Поэтому мы представляем пошаговое руководство по тому, как сделать чат с интеграцией CarrotQuest в приложении Flutter.

В данной статье я опишу, в какой последовательности нужно производить отправку и обработку данных, а код самого приложения на Flutter будет доступен позже.


Шаг 0. Генерация токена CarrotQuest

Тут всё крайне просто. Следуем инструкции, получаем токен и далее используем его во всех наших запросах на сервера CarrotQuest.


Шаг 1. Регистрация нового пользователя

Для отправки сообщений сначала необходимо создать нового пользователя. CarrotQuest поддерживает два варианта идентификации - внутренняя и свободная. Внутренняя нас не интересует, а вот свободную мы будем использовать для регистрации чата и сообщений. В нашем приложении в качестве логина используется номер телефона пользователя, либо номер договора. Оба варианта хорошо подходят для генерации нового пользователя в CarrotQuest. В ответе сервера получаем внутренний ID пользователя, запоминаем его в нашем приложении.

Делаем запрос, описание тут.

POST https://api.carrotquest.io/v1/users/{id}/events

с указанием ID пользователя. В нашем случае это номер телефона пользователя из приложения. Также указываем любое значение поля event и by_user_id в true, что укажет системе, что нужно создать пользователя, если такого ID еще нет в системе.

Если всё прошло успешно, то в ответе сервера будет ID пользователя в системе CarrotQuest. Его стоит сохранить для будущего использования.

{
"meta": {
    "status": 200
    },
    "data": {
        "id": "883065057192182532", --> наш ID
        "created": 1617377558,
        "type": {
            "id": "883031503280275942",
            "name": "1",
            "score": 0,
            "visible": true,
            "active": true
        },
    "user": "883065056235881216",
    "props": { }
    }
}

Шаг 2. Установка имени пользователя

После создания пользователю будет присвоено случайное имя - например, "Железная синяя антилопа". Это не очень удобно, поэтому мы переименуем нашего пользователя, указав ему имя и фамилию, которые снова возьмем из приложения.

Для этого используем запрос, описанный тут. Стоит отметить, что он позволяет задавать огромное количество полей. Мы же ограничимся полем $name.

POST https://api.carrotquest.io/v1/users/{id}/props

Ответ сервера должен сигнализировать об успехе операции.

{
    "meta": {
        "affected_props": ["$name"],
        "ignored_operations": [ ],
        "not_changed_props": [ ],
        "status": 200
    },
    "data": {
        "id": "883065056235881216",
        "app": "42698"
    }
}

В CarrotQuest, как мы видим, теперь есть пользователь с именем "Иван Петров".


Шаг 3. Создание нового чата

Используем запрос, описанный тут.

POST https://api.carrotquest.io/v1/users/{id}/startconversation

Стоит отметить, что тут в качестве ID пользователя нужно использовать именно внутренний ID CarrotQuest. Тот самый, что мы сохранили после создания пользователя в Шаге 1. В поле body мы указываем текст сообщения и отправляем запрос.

В ответе сервера получим ID нашего чата. Его тоже сохраняем внутри приложения.

{
    "meta": {
        "status": 200
    },
    "data": {
        "id": "883078703377023045" --> ID свежесозданного чата
    }
}

Сообщение сразу появится в панели CarrotQuest.


Шаг 4. Отправка сообщений в чат

Имея на руках ID пользователя в CarrotQuest и ID беседы, можно начинать общение. Используем этот запрос.

POST https://api.carrotquest.io/v1/conversations/{id}/reply

В параметрах указываем

{id} - идентификатор беседы, полученный в Шаге 3

from_user - ID пользователя по CarrotQuest, полученный в Шаге 1

body - текст сообщения.

В ответе сервер вернет ID созданного сообщения.

{
    "meta": {
        "status": 200
    },
    "data": {
        "id": "883080653812270032"
    }
}

Сообщение сразу появится в панели CarrotQuest.


Основной функционал готов. Подготовим наше приложение. Теперь при входе в приложение и открытии окна чата мы должны:

  1. Сделать запрос, проверяющий, есть ли такой пользователь в CarrotQuest.
  2. Если пользователь есть, то загрузить все диалоги. Если нет, то провести шаги 1-2.
  3. При выборе диалога загрузить все сообщения этого диалога.
  4. Для отправки сообщения используем данные из Шага 4.
  5. Для получения ответов в реальном времени можно использовать WebSockets. Детальное описание есть здесь.