sendForm

Отправляет посетителю форму прямо в ленту чата: имя, телефон, удобный день. Посетитель заполняет и отправляет её один раз — ответ приходит уведомлением Ответ формой с полями по ключам. Удобно для записи на занятие и заявок.

Параметры

Поле формы:

Пример запроса

Запись на пробное занятие от имени сотрудника:

curl

curl -X POST "$GRATIO_URL/v1/instances/$GRATIO_ID/sendForm" \
  -H "Authorization: Bearer $GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4",
    "title": "Запись на пробное",
    "body": "Оставьте, как с вами связаться",
    "fields": [
      {
        "key": "name",
        "label": "Имя",
        "type": "text",
        "required": true
      },
      {
        "key": "phone",
        "label": "Телефон",
        "type": "tel",
        "required": true
      },
      {
        "key": "day",
        "label": "День",
        "type": "select",
        "options": [
          "Суббота",
          "Воскресенье"
        ]
      }
    ],
    "submitText": "Записаться",
    "consent": true,
    "author": {
      "kind": "operator",
      "name": "Ольга"
    },
    "clientMessageId": "form-trial-1"
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/v1/instances/{os.environ['GRATIO_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['GRATIO_TOKEN']}"}

url = f"{BASE}/sendForm"
payload = {
    "chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4",
    "title": "Запись на пробное",
    "body": "Оставьте, как с вами связаться",
    "fields": [
        {
            "key": "name",
            "label": "Имя",
            "type": "text",
            "required": True,
        },
        {
            "key": "phone",
            "label": "Телефон",
            "type": "tel",
            "required": True,
        },
        {
            "key": "day",
            "label": "День",
            "type": "select",
            "options": ["Суббота", "Воскресенье"],
        },
    ],
    "submitText": "Записаться",
    "consent": True,
    "author": {"kind": "operator", "name": "Ольга"},
    "clientMessageId": "form-trial-1",
}
response = requests.post(url, json=payload, headers=HEADERS, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/v1/instances/${GRATIO_ID}`;
const auth = { Authorization: `Bearer ${GRATIO_TOKEN}` };

const url = `${base}/sendForm`;
const payload = {
  chatId: "vq3k7m2x4a6b2c4d6e7f2g3h4",
  title: "Запись на пробное",
  body: "Оставьте, как с вами связаться",
  fields: [
    { key: "name", label: "Имя", type: "text", required: true },
    { key: "phone", label: "Телефон", type: "tel", required: true },
    {
      key: "day",
      label: "День",
      type: "select",
      options: ["Суббота", "Воскресенье"],
    },
  ],
  submitText: "Записаться",
  consent: true,
  author: { kind: "operator", name: "Ольга" },
  clientMessageId: "form-trial-1",
};
const response = await fetch(url, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/v1/instances/' . getenv('GRATIO_ID');
$auth = 'Authorization: Bearer ' . getenv('GRATIO_TOKEN');
$url = $base . '/sendForm';
$payload = [
    'chatId' => 'vq3k7m2x4a6b2c4d6e7f2g3h4',
    'title' => 'Запись на пробное',
    'body' => 'Оставьте, как с вами связаться',
    'fields' => [
        [
            'key' => 'name',
            'label' => 'Имя',
            'type' => 'text',
            'required' => true,
        ],
        [
            'key' => 'phone',
            'label' => 'Телефон',
            'type' => 'tel',
            'required' => true,
        ],
        [
            'key' => 'day',
            'label' => 'День',
            'type' => 'select',
            'options' => ['Суббота', 'Воскресенье'],
        ],
    ],
    'submitText' => 'Записаться',
    'consent' => true,
    'author' => ['kind' => 'operator', 'name' => 'Ольга'],
    'clientMessageId' => 'form-trial-1',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [$auth, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK — id сообщения с формой и id формы:

{"idMessage": "o5d3c2b1a0f9e8d7c6b5a4f3e2d1c0b", "formId": "f3a91c2e07b4d"}

Ответ посетителя придёт уведомлением Ответ формой: formResponseMessage.fields — {"name": "Мария", "phone": "+79991234567", "day": "Суббота"}.

Ещё примеры

Форма контакта окна

Без fields и с formId: "contact" окно покажет свою форму: телефон или почта, имя, удобный мессенджер из настройки siteMessengers:

curl -X POST "$GRATIO_URL/v1/instances/$GRATIO_ID/sendForm" \
  -H "Authorization: Bearer $GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4", "formId": "contact"}'

Своя форма с formId: "contact" проверяется так же: нужен телефон или почта.

Согласие

consent: true — форма просит согласие на обработку данных. Как именно, решает настройка siteConsent:

Данное согласие приходит в ответе формы — поле consent. Подробно — в статье Настройки окна.

Как ведёт себя форма

• Посетитель отправляет форму один раз, повторно её не открыть.
• В ленте и истории ваша форма — typeMessage: "formMessage", см. Свои сообщения.
• Свободный ввод в окне открыт и при форме.

Ошибки

Общие правила — в статье Ответы и ошибки.

Что дальше

• Ответ формой — что приходит, когда посетитель отправил форму.
• sendInteractiveButtons и sendButtons — быстрые ответы кнопками.
• Настройки окна — согласие и мессенджеры для формы контакта.