Документация
Один 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
| Поле | Что писать |
|---|---|
| channel | email, sms или whatsapp. Обязательно. |
| to | Адрес почты или израильский мобильный номер, например +972501234567. Обязательно. |
| from | Для писем: адрес на подтверждённом домене. Для SMS: одобренное имя отправителя. Не укажете, возьмём первое одобренное имя. |
| subject | Тема письма. Для писем обязательна, если нет шаблона. |
| text | Текст сообщения. |
| html | Письмо в HTML. Не пришлёте, соберём сами из текста, справа налево там, где нужно. |
| template | Название шаблона, вместо text. |
| variables | Что подставить в шаблон. |
| language | he, 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-code | code, app, minutes |
| order-confirmed | name, order, app |
| receipt | name, 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));
}
Тестовый режим
С тестовым ключом никому ничего не уходит, но в журнале сообщения выглядят как настоящие. Что с ними будет, зависит от получателя:
| Получатель | Что будет |
|---|---|
| +972500000000 | SMS не отправится. |
| [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_....
Та же документация обычным текстом, чтобы ИИ-инструменты могли прочитать её сами: