Twilio для JavaScript (Node.js): полное руководство с примерами

1. Что это и зачем нужна

Twilio — это облачная платформа Communications Platform as a Service (CPaaS), которая предоставляет разработчикам программные интерфейсы (API) для интеграции функций голосовой связи, SMS, MMS, видео и аутентификации (2FA) в веб- и мобильные приложения. Библиотека twilio для Node.js является официальным SDK, который абстрагирует сложность прямых HTTP-запросов к REST API Twilio, предоставляя удобный и типобезопасный интерфейс для работы со всеми сервисами платформы.

Зачем она нужна? В современном мире коммуникации являются неотъемлемой частью любого бизнеса. Twilio позволяет разработчикам быстро и без масштабных капитальных затрат добавлять такие функции, как отправка уведомлений по SMS, совершение автоматических звонков (например, для подтверждения заказа или напоминания о встрече), создание голосовых меню (IVR) и многое другое. Вместо того чтобы разворачивать и поддерживать собственную инфраструктуру операторов связи, вы получаете доступ к глобальной сети операторов через простой API.

Библиотека для Node.js особенно популярна благодаря асинхронной природе JavaScript и широкому распространению Node.js в бэкенд-разработке. Она поддерживает Promises и async/await, что делает код чистым и читаемым. SDK автоматически обрабатывает повторные попытки при сетевых ошибках, управляет аутентификацией через Account SID и Auth Token, а также предоставляет встроенные типы для TypeScript, что значительно упрощает разработку и отладку.

2. Установка

Установка библиотеки производится через менеджер пакетов npm. Убедитесь, что у вас установлен Node.js версии 14 или выше.

npm install twilio

Для использования TypeScript установка дополнительных типов не требуется, так как библиотека содержит встроенные определения типов.

npm install twilio @types/twilio

После установки вы можете импортировать библиотеку в свой проект:

const twilio = require('twilio'); // CommonJS
// или
import twilio from 'twilio'; // ES Modules

3. Быстрый старт — минимальный рабочий пример

Перед началом работы вам понадобятся учетные данные из консоли Twilio: Account SID и Auth Token. Также необходимо приобрести телефонный номер в панели управления Twilio.

// Импортируем библиотеку
const twilio = require('twilio');

// Ваши учетные данные из консоли Twilio
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Замените на ваш SID
const authToken = 'your_auth_token'; // Замените на ваш токен

// Создаем экземпляр клиента
const client = twilio(accountSid, authToken);

// Отправляем SMS
client.messages
  .create({
    body: 'Привет, мир! Это тестовое сообщение от Twilio.',
    from: '+1234567890', // Ваш номер Twilio
    to: '+0987654321'    // Номер получателя
  })
  .then(message => console.log('Сообщение отправлено. SID:', message.sid))
  .catch(error => console.error('Ошибка:', error));

Этот минимальный пример отправляет SMS-сообщение. После успешной отправки в консоль будет выведен уникальный идентификатор сообщения (SID).

4. Основные методы/функции/классы

4.1. client.messages.create()

Сигнатура: client.messages.create(params: MessageCreateParams): Promise<MessageInstance>

Описание: Отправляет SMS или MMS сообщение. Параметры включают body (текст), from (номер отправителя), to (номер получателя) и опциональные mediaUrl (для MMS) и statusCallback.

client.messages
  .create({
    body: 'Ваш код подтверждения: 1234',
    from: '+1234567890',
    to: '+0987654321',
    statusCallback: 'https://yourdomain.com/sms-status'
  })
  .then(msg => console.log('SID:', msg.sid));

4.2. client.messages.list()

Сигнатура: client.messages.list(params?: MessageListParams): Promise<Array<MessageInstance>>

Описание: Возвращает список отправленных или полученных сообщений с возможностью фильтрации по дате, номеру и статусу.

client.messages
  .list({ limit: 5 })
  .then(messages => messages.forEach(m => console.log(m.sid, m.body)));

4.3. client.calls.create()

Сигнатура: client.calls.create(params: CallCreateParams): Promise<CallInstance>

Описание: Инициирует голосовой звонок. Обязательные параметры: from, to и url (Twilio Markup Language XML, определяющий поведение звонка).

client.calls
  .create({
    url: 'http://demo.twilio.com/docs/voice.xml',
    to: '+0987654321',
    from: '+1234567890'
  })
  .then(call => console.log('Call SID:', call.sid));

4.4. client.calls.list()

Сигнатура: client.calls.list(params?: CallListParams): Promise<Array<CallInstance>>

Описание: Получает список совершенных звонков с возможностью фильтрации по статусу, дате и направлению (входящий/исходящий).

client.calls
  .list({ status: 'completed', limit: 10 })
  .then(calls => calls.forEach(c => console.log(c.sid, c.duration)));

4.5. client.lookups.phoneNumbers()

Сигнатура: client.lookups.phoneNumbers(phoneNumber: string): Promise<PhoneNumberInstance>

Описание: Выполняет Lookup-запрос для проверки и валидации телефонного номера. Возвращает информацию о типе номера (мобильный, стационарный), операторе и стране.

client.lookups
  .phoneNumbers('+1234567890')
  .fetch()
  .then(info => console.log('Carrier:', info.carrier.name, 'Type:', info.carrier.type));

4.6. client.verify.services()

Сигнатура: client.verify.services.create(params: ServiceCreateParams): Promise<ServiceInstance>

Описание: Создает сервис верификации для реализации двухфакторной аутентификации (2FA). После создания сервиса вы можете отправлять коды подтверждения.

client.verify.services
  .create({ friendlyName: 'My 2FA Service' })
  .then(service => console.log('Service SID:', service.sid));

4.7. client.verify.services().verifications.create()

Сигнатура: client.verify.services(serviceSid).verifications.create(params: VerificationCreateParams): Promise<VerificationInstance>

Описание: Отправляет код подтверждения на указанный номер телефона (SMS или голосовой вызов). Параметр channel может быть 'sms' или 'call'.

client.verify.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .verifications
  .create({ to: '+0987654321', channel: 'sms' })
  .then(verification => console.log('Status:', verification.status));

4.8. client.verify.services().verificationChecks.create()

Сигнатура: client.verify.services(serviceSid).verificationChecks.create(params: VerificationCheckCreateParams): Promise<VerificationCheckInstance>

Описание: Проверяет введенный пользователем код подтверждения. Возвращает статус 'approved' при успешной проверке.

client.verify.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .verificationChecks
  .create({ to: '+0987654321', code: '123456' })
  .then(check => console.log('Valid:', check.valid, 'Status:', check.status));

4.9. client.incomingPhoneNumbers()

Сигнатура: client.incomingPhoneNumbers.list(params?: IncomingPhoneNumberListParams): Promise<Array<IncomingPhoneNumberInstance>>

Описание: Возвращает список всех телефонных номеров, приобретенных в вашем аккаунте Twilio.

client.incomingPhoneNumbers
  .list({ limit: 20 })
  .then(numbers => numbers.forEach(n => console.log(n.phoneNumber, n.friendlyName)));

5. Реальный практический пример (100-200 строк кода)

Рассмотрим пример создания простого сервиса уведомлений на Express.js, который отправляет SMS при регистрации нового пользователя и совершает проверочный звонок.

const express = require('express');
const twilio = require('twilio');

const app = express();
app.use(express.json());

// Конфигурация
const config = {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  twilioNumber: process.env.TWILIO_PHONE_NUMBER,
  verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID
};

const client = twilio(config.accountSid, config.authToken);

// База данных пользователей (в реальном проекте — MongoDB/PostgreSQL)
const users = [];

// 1. Регистрация пользователя
app.post('/api/register', async (req, res) => {
  try {
    const { name, phone } = req.body;

    if (!name || !phone) {
      return res.status(400).json({ error: 'Name and phone are required' });
    }

    // Сохраняем пользователя
    const user = { id: users.length + 1, name, phone, verified: false };
    users.push(user);

    // Отправляем приветственное SMS
    await client.messages.create({
      body: `Добро пожаловать, ${name}! Ваш ID: ${user.id}. Подтвердите номер, введя код из SMS.`,
      from: config.twilioNumber,
      to: phone
    });

    // Отправляем код подтверждения через Verify API
    await client.verify.services(config.verifyServiceSid)
      .verifications
      .create({ to: phone, channel: 'sms' });

    res.status(201).json({ 
      message: 'User registered. Verification code sent.',
      userId: user.id 
    });
  } catch (error) {
    console.error('Registration error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// 2. Подтверждение номера телефона
app.post('/api/verify', async (req, res) => {
  try {
    const { phone, code } = req.body;

    if (!phone || !code) {
      return res.status(400).json({ error: 'Phone and code are required' });
    }

    // Проверяем код
    const check = await client.verify.services(config.verifyServiceSid)
      .verificationChecks
      .create({ to: phone, code });

    if (check.valid) {
      // Находим пользователя и обновляем статус
      const user = users.find(u => u.phone === phone);
      if (user) {
        user.verified = true;
      }

      // Совершаем приветственный звонок (опционально)
      await client.calls.create({
        url: 'https://demo.twilio.com/welcome/voice/', // TwiML для приветствия
        to: phone,
        from: config.twilioNumber
      });

      return res.json({ 
        message: 'Phone verified successfully! Welcome call initiated.',
        verified: true 
      });
    } else {
      return res.status(400).json({ 
        error: 'Invalid verification code',
        verified: false 
      });
    }
  } catch (error) {
    console.error('Verification error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// 3. Отправка массовой рассылки (осторожно: спам-фильтры!)
app.post('/api/broadcast', async (req, res) => {
  try {
    const { message } = req.body;

    if (!message) {
      return res.status(400).json({ error: 'Message is required' });
    }

    const results = [];
    
    // Отправляем сообщение всем верифицированным пользователям
    for (const user of users) {
      if (user.verified) {
        try {
          const msg = await client.messages.create({
            body: message,
            from: config.twilioNumber,
            to: user.phone
          });
          results.push({ phone: user.phone, status: 'sent', sid: msg.sid });
        } catch (err) {
          results.push({ phone: user.phone, status: 'failed', error: err.message });
        }
      }
    }

    res.json({ 
      total: users.length,
      sent: results.filter(r => r.status === 'sent').length,
      failed: results.filter(r => r.status === 'failed').length,
      details: results 
    });
  } catch (error) {
    console.error('Broadcast error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// 4. Получение статусов сообщений (Webhook)
app.post('/api/sms-status', (req, res) => {
  const messageSid = req.body.MessageSid;
  const messageStatus = req.body.MessageStatus;
  
  console.log(`Message ${messageSid} status: ${messageStatus}`);
  
  // Здесь можно обновить статус в базе данных
  res.sendStatus(200);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

6. Советы по производительности и типичные ошибки

Советы по производительности:

1. Используйте пул соединений: Twilio SDK использует HTTP-клиент с поддержкой keep-alive. Для высок