SDK de PHP

Enviar SMS, WhatsApp y OTP desde PHP con el SDK oficial

envoisms/envoisms-php es el SDK oficial de PHP de EnvoiSMS.ma. Un cliente, una clave API: envío de SMS y WhatsApp, códigos OTP, envíos masivos, estado de los mensajes, verificación de webhooks y saldo de la cuenta. También es la base del paquete de Laravel envoisms/laravel-otp.

cURL REST API

curl -X POST https://api.envoisms.ma/v1/messages \
  -H "Authorization: Bearer env_live_votretoker" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212661234567",
    "message": "Votre code de confirmation est : 849201. Expire dans 3 minutes.",
    "from": "VOTREMARQUE"
  }'

● Routes locales MarocIAM • Inwi • Orange

https://api.envoisms.ma/v1

Rutas locales

Maroc Telecom (IAM) • Inwi • Orange

Acuses DLR reales

Firma HMAC-SHA256

Tarifas en MAD

dès 0,60 MAD/SMS • 5 MAD offerts

Instalación y primer SMS

composer require envoisms/envoisms-php, y luego $client = new EnvoiSMS\Client(getenv('ENVOISMS_API_KEY')). $client->send(['to' => '+212600000000', 'message' => '…', 'from' => 'MiNegocio']) devuelve el id del mensaje, que encontrará con getMessage() y en sus webhooks.

'from': su Sender ID validado, u omítalo para el remitente por defecto
sendBulk(['messages' => [...], 'from' => ...]) para un envío masivo
getMessage($id) y listMessages(50, 0) para seguir sus envíos

Envíos reintentables y gestión de errores

Cada send() y sendBulk() lleva un Idempotency-Key, generado o pasado como segundo argumento: un reintento tras un timeout nunca factura dos veces el mismo mensaje. El propio cliente reintenta las respuestas 5xx y los errores de cURL hasta maxRetries veces (2 por defecto) con espera exponencial, y luego lanza EnvoiSMSError con statusCode y errorCode.

new Client(getenv('ENVOISMS_API_KEY'), maxRetries: 3, timeoutSeconds: 20)
catch (EnvoiSMS\EnvoiSMSError $e): $e->statusCode, $e->errorCode

SMS o WhatsApp: elegir el canal

El SMS es el canal por defecto: llega a todos los móviles marroquíes (IAM, Inwi, Orange) sin más configuración que la clave API. 'channel' => 'whatsapp' envía desde su propio número de WhatsApp Business: debe estar conectado (si no, 403 WHATSAPP_NOT_CONNECTED), y un texto libre solo se acepta dentro de las 24 horas siguientes al último mensaje del cliente (si no, 400 OUT_OF_24H_WINDOW). Fuera de esa ventana, envíe una plantilla aprobada. No se cobra nada cuando la API rechaza.

'template' => ['name' => 'order_shipped', 'language' => 'fr', 'variables' => ['89240']]
'cascade' => true: paso automático a SMS si el número no tiene WhatsApp

Códigos OTP y webhooks

$client->sendOtp(['to' => …, 'brand' => 'MiNegocio', 'code_length' => 6, 'expiry' => 600]) devuelve un session_id; $client->checkOtp($sessionId, $code) devuelve verified. getOtpSession() lee el estado de una sesión sin consumir un intento. Para un webhook de estado, Client::verifyWebhookSignature($rawBody, $signature, $secret) comprueba la cabecera X-EnvoiSMS-Signature sobre el cuerpo bruto de la petición.

'channel' => 'whatsapp' en sendOtp(): código por WhatsApp a través del remitente compartido, sin conexión
getBalance(), listPacks(), createTopup() para la cuenta
createOptout($phone) para registrar un STOP

Preguntas frecuentes

Todo lo que debe saber sobre SDK de PHP.

¿Cómo verifico un webhook de estado en PHP?

Lea el cuerpo bruto con file_get_contents('php://input') — no el array ya decodificado — y páselo a Client::verifyWebhookSignature() con la cabecera X-EnvoiSMS-Signature y su secreto de webhook. Procese la entrega solo si la verificación tiene éxito.

¿Puedo usar el SDK con Laravel?

Sí, directamente, o mediante el paquete envoisms/laravel-otp, que se apoya en él y añade un canal de notificación y una fachada de Laravel.

¿Qué pasa si mi script envía dos veces el mismo SMS?

Nada más: con el mismo Idempotency-Key, la API devuelve la respuesta original sin reenviar ni facturar el mensaje. Una clave es válida 24 horas.

¿Listo para integrar con SDK de PHP?

Cree su cuenta en menos de 2 minutos. Obtenga 5 MAD de crédito gratis de inmediato para probar la API.

Activar mi cuenta gratuita Ver documentación API