Otipi

Документация

Один API для почты, SMS и WhatsApp. Все запросы идут на https://otipi.co.il/v1, данные в формате JSON.

Быстрый старт

Создайте ключ в кабинете и отправьте один запрос:

curl https://otipi.co.il/v1/messages \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+972501234567",
    "template": "login-code",
    "variables": { "code": "482917", "app": "MyApp", "minutes": 5 }
  }'

Ответ приходит сразу, ещё до того, как сообщение ушло:

{
  "id": "msg_7Qk2LxWb9RtY3nPd5sAe",
  "channel": "sms",
  "to": "+972501234567",
  "status": "queued",
  "mode": "test",
  "segments": 1,
  "created_at": "2026-11-10T08:15:02.000Z"
}

Ключи

Ключ передаётся в каждом запросе, в заголовке Authorization: Bearer. Это секрет: используйте его только на сервере, никогда в браузере или в мобильном приложении.

Ключ на sk_test_ работает в тестовом режиме и никому ничего не отправляет. Ключ на sk_live_ отправляет по-настоящему.

Библиотека для Node.js

Один файл, без зависимостей, для Node 18 и новее. Скачайте otipi.js, положите в проект и подключите:

import { Otipi } from './otipi.js';

const otipi = new Otipi(process.env.OTIPI_KEY);

// Код входа: отправляем, потом проверяем, что ввёл человек
await otipi.otp.send({ to: '+972501234567', app: 'MyApp' });
const { valid } = await otipi.otp.verify({ to: '+972501234567', code: '482917' });

// Обычное сообщение
const message = await otipi.send({
  channel: 'sms',
  to: '+972501234567',
  text: 'Ваш заказ уже в пути.',
});

// Что с сообщением
const { status } = await otipi.messages.get(message.id);

Если API вернул ошибку, библиотека бросит OtipiError с полями code и status. Без библиотеки всё работает так же, через fetch или curl: примеры ниже.

Как отправить сообщение

POST /v1/messages

ПолеЧто писать
channelemail, sms или whatsapp. Обязательно.
toАдрес почты или израильский мобильный номер, например +972501234567. Обязательно.
fromДля писем: адрес на подтверждённом домене. Для SMS: одобренное имя отправителя. Не укажете, возьмём первое одобренное имя.
subjectТема письма. Для писем обязательна, если нет шаблона.
textТекст сообщения.
htmlПисьмо в HTML. Не пришлёте, соберём сами из текста, справа налево там, где нужно.
templateНазвание шаблона, вместо text.
variablesЧто подставить в шаблон.
languagehe, ar, ru или en, для готовых шаблонов. Если не указать, будет he.

Пример на Node.js:

const response = await fetch('https://otipi.co.il/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OTIPI_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channel: 'email',
    from: 'MyApp <[email protected]>',
    to: '[email protected]',
    subject: 'Добро пожаловать',
    text: 'Здравствуйте, Дана! Ваш аккаунт готов.',
  }),
});
const message = await response.json();

Чтобы при повторе запроса сообщение не ушло дважды, добавьте заголовок Idempotency-Key со своим значением. Повторный запрос с тем же значением просто вернёт первое сообщение.

Что с сообщением

GET /v1/messages/:id покажет сообщение и всё, что с ним было. GET /v1/messages покажет последние; отобрать их можно через limit, channel и status.

СтатусЧто значит
queuedПриняли, скоро отправим.
sentПередали оператору связи.
deliveredДошло до получателя.
openedПисьмо открыли.
failedОтправить не получилось. Причина в поле error.
bouncedПисьмо вернулось: такого адреса нет, или он не принял письмо.

Коды входа

Всего два запроса: первый отправляет код, второй проверяет, что ввёл человек. Код придумываем и храним мы, попытки тоже считаем мы.

# 1. Отправляем код
curl https://otipi.co.il/v1/otp/send \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+972501234567", "app": "MyApp" }'

# 2. Проверяем, что ввёл человек
curl https://otipi.co.il/v1/otp/verify \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+972501234567", "code": "482917" }'

В /v1/otp/send можно добавить channel (sms, whatsapp или email), language (he, ar, ru или en), length (от 4 до 8 цифр) и ttl_minutes (сколько минут действует код, до 30). В ответ придёт { "id": "otp_...", "status": "pending", ... }. /v1/otp/verify отвечает { "valid": true } или { "valid": false, "reason": "wrong_code" }.

Код действует 5 минут, ввести его можно 5 раз. Одному человеку уходит не больше 5 кодов в час.

В WhatsApp текст всегда один и тот же: код из 6 цифр, действует 5 минут, на иврите или английском. Другие сообщения в WhatsApp пока отправлять нельзя.

Шаблоны

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

НазваниеЧто подставляется
login-codecode, app, minutes
order-confirmedname, order, app
receiptname, amount, app

Свои шаблоны создаются в кабинете. Место для значения пишется так: {{name}}.

Webhooks

Добавьте в кабинете адрес на своём сервере, и при каждой смене статуса мы будем присылать туда запрос POST: message.sent, message.delivered, message.opened, message.failed, message.bounced.

{
  "id": "evt_Hc91VdKq2mZx8LpT4rNb",
  "type": "message.delivered",
  "created_at": "2026-11-10T08:15:04.000Z",
  "data": { "id": "msg_7Qk2LxWb9RtY3nPd5sAe", "channel": "sms", "to": "+972501234567", "status": "delivered" }
}

Ответьте кодом 2xx в течение 8 секунд. Не ответите, попробуем ещё раз через 10 секунд и через минуту.

В каждом запросе есть заголовок Otipi-Signature. С библиотекой его проверка занимает одну строку:

// body: тело запроса как пришло, до JSON.parse
if (!Otipi.verifyWebhook(body, request.headers['otipi-signature'], secret)) {
  return response.writeHead(400).end();
}

А без библиотеки вот так:

import crypto from 'node:crypto';

// body: тело запроса как пришло, до JSON.parse
function isFromOtipi(body, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Тестовый режим

С тестовым ключом никому ничего не уходит, но в журнале сообщения выглядят как настоящие. Что с ними будет, зависит от получателя:

ПолучательЧто будет
+972500000000SMS не отправится.
[email protected]Письмо вернётся. Подойдёт любой адрес, который начинается на bounce.
[email protected]Письмо дойдёт, а потом его «откроют». Подойдёт любой адрес, который начинается на open.
Любой другойСообщение дойдёт.

В тестовом режиме /v1/otp/send возвращает и сам код, в поле test_code. В день можно отправить до 500 тестовых сообщений.

Ошибки и ограничения

При ошибке приходит подходящий код HTTP и такой ответ: { "error": { "code": "invalid_recipient", "message": "..." } }.

КодЧто случилось
unauthorizedНет ключа, ключ неверный или удалён.
invalid_recipientПолучатель не подходит для этого канала. SMS и WhatsApp пока уходят только на израильские номера.
missing_variablesНе хватает значений для шаблона.
domain_not_verifiedАдрес отправителя на домене, который ещё не подтверждён.
identity_not_verifiedЧтобы отправлять настоящие SMS, нужно один раз подтвердить личность.
live_unavailableВ этом канале настоящая отправка ещё не включена.
whatsapp_codes_onlyС рабочим ключом в WhatsApp уходят только коды входа. Используйте /v1/otp/send.
rate_limitedБольше 600 запросов в минуту с одного ключа.
monthly_limit_reachedПисьма по тарифу на этот месяц закончились.

Для ИИ-инструментов

Собираете приложение в Lovable, Cursor, Base44, Supabase или другом ИИ-инструменте? Вот готовые инструкции и текст, который можно просто скопировать.

Supabase Auth (Send SMS Hook)

В Supabase откройте Auth -> Hooks -> Send SMS Hook, выберите HTTP Request, вставьте адрес https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto и добавьте заголовок Authorization: Bearer sk_live_... (или секрет Standard Webhooks). Otipi пришлёт код входа в WhatsApp, а если не получится, то по SMS.

Lovable и Cursor

Скопируйте этот текст в Lovable или Cursor: он объяснит, как сделать вход по телефону и отправку писем через Otipi.

Add Otipi to this project. Otipi is an API for login codes, SMS and email to recipients in Israel.

Rules:
- Call Otipi from server code only (an API route, a server action or an edge function). The key is a secret: read it from the environment variable OTIPI_KEY and never send it to the browser.
- Base URL: https://otipi.co.il/v1. Every request carries the header "Authorization: Bearer <key>" and a JSON body.
- A key that starts with sk_test_ delivers nothing and returns the code in "test_code". Use it while building.

Phone login in two calls:
1. POST /v1/otp/send {"to": "+972501234567", "app": "<the name of this app>"} -> 201 {"id", "status": "pending", "expires_at"}
   Optional: "channel": "sms" | "whatsapp" | "email" | "auto", "language": "he" | "ar" | "ru" | "en".
2. POST /v1/otp/verify {"to": "+972501234567", "code": "<what the person typed>"} -> {"valid": true} or {"valid": false, "reason": "wrong_code" | "expired_or_missing" | "too_many_attempts"}
   Sign the person in only when "valid" is true.

Supabase Auth (Send SMS Hook):
- In Supabase Dashboard -> Auth -> Hooks -> Send SMS Hook, set URL to https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto with Authorization: Bearer <key> (or Standard Webhooks secret).

Base44:
- Connect using OpenAPI specification at https://otipi.co.il/openapi.json (https://otipi.co.il/openapi.json).

Other messages: POST /v1/messages {"channel": "sms" | "email", "to": "...", "text": "..."} -> 202 {"id", "status": "queued"}. An email also needs "subject" and, with a live key, "from" on a verified domain.

Phone numbers are Israeli mobiles written as +9725XXXXXXXX. An error comes as {"error": {"code", "message"}} with a fitting HTTP status: show the person a short message and log the code.

Full reference: https://otipi.co.il/llms-full.txt
OpenAPI: https://otipi.co.il/openapi.json

Base44

В Base44 добавьте внешний API по описанию OpenAPI: адрес https://otipi.co.il/openapi.json, ключ Bearer sk_live_....

Та же документация обычным текстом, чтобы ИИ-инструменты могли прочитать её сами: