Vai al contenuto
OmniMessage

API gateway di messaggistica

Un’unica API per tutti i canali di messaggistica

Invia messaggi WhatsApp Business, SMS, Telegram, Messenger, Instagram e TikTok da un unico endpoint REST. Prepagato, con addebito per messaggio in uscita, webhook di consegna e modalità di test.

Ottieni una chiave APILeggi la documentazione
A partire da
0,0003 $
per messaggio in uscita
Alla registrazione
100
messaggi gratuiti
Vincoli
Nessuno
prepagato, senza contratto
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
    "to": "+971501234567",
    "type": "text",
    "text": { "body": "Your order #1042 has shipped." },
    "reference": "order-1042"
  }'
202 Accepted
{
  "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
  "object": "message",
  "mode": "live",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+971501234567",
  "from": "+971800123456",
  "type": "text",
  "content": {
    "text": { "body": "Your order #1042 has shipped." }
  },
  "status": "queued",
  "error": null,
  "reference": "order-1042",
  "metadata": {},
  "billing": {
    "source": "wallet",
    "amount_micros": 1000,
    "package_grant_id": null,
    "refunded": false
  },
  "created_at": "2026-10-05T09:30:00.000Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null
}
  • Tipi di canale7 dietro un unico endpoint
  • Tipi di messaggio9, dal testo agli elenchi interattivi
  • Prezzo a partire da0,0003 $ per messaggio in uscita
  • Limite di frequenza100 richieste al secondo per chiave
  • Dimensione del batchFino a 100 messaggi per richiesta
  • Nuovi tentativi dei webhook8, con backoff da 30 secondi a 24 ore
  • Finestra di idempotenza24 ore
  • Modalità di testGratuita, senza bisogno di canali
  • Messaggi non riuscitiRimborsati automaticamente
  • Messaggi in entrataGratuiti

Canali

Sette tipi di canale, un solo formato di richiesta

Collega i mittenti che possiedi già. Ognuno diventa un ID canale da passare allo stesso endpoint, e ognuno restituisce gli stessi stati.

Confronta i canali

Come funziona

Dalla registrazione a un messaggio consegnato in quattro passaggi

Nessuna chiamata con un commerciale e nessun impegno minimo. Puoi fare la tua prima chiamata API in modalità di test un minuto dopo aver creato l’account.

  1. Passaggio 01

    Crea un account

    Registrati, verifica il tuo indirizzo email e crea una chiave API nella console. Le chiavi di test funzionano subito, prima di collegare qualsiasi canale.

  2. Passaggio 02

    Collega un canale

    Accedi con Facebook o TikTok dalla console per collegare un numero WhatsApp, una Pagina o un account aziendale. Aggiungi un bot Telegram o un numero Twilio con le relative credenziali, dalla console o con POST /v1/channels.

  3. Passaggio 03

    Invia da un unico endpoint

    POST /v1/messages riceve un ID canale, un destinatario e un oggetto di contenuto tipizzato. Il formato della richiesta è lo stesso su tutti i canali.

  4. Passaggio 04

    Segui ogni consegna

    I webhook firmati segnalano gli stati inviato, consegnato, letto e non riuscito. La stessa cronologia è disponibile nella console e con GET /v1/messages.

Tipi di messaggio

Quello che invii è quello che vedono

Ogni messaggio ha un tipo e un oggetto di contenuto sotto la chiave di quel tipo. Scegline uno per vedere il corpo della richiesta accanto al messaggio che produce.

Tutti i tipi di messaggio
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "Il tuo ordine n. 1042 è stato spedito. Seguilo su https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}

Testo semplice, accettato da tutti i tipi di canale. Imposta preview_url per consentire al canale di mostrare l’anteprima di un link.

CanaliWhatsApp Business, SMS, SMS OTP, Telegram, Messenger, Instagram e TikTok

Console

Una console per tutto ciò che non è codice

Crea chiavi, collega canali, cerca nel registro dei messaggi, riesegui le consegne dei webhook e gestisci la fatturazione. Tutto ciò che la console mostra è disponibile anche tramite l’API.

Panoramica. Saldo del portafoglio, crediti dei pacchetti residui e volume in uscita degli ultimi 30 giorni, per account e per modalità. Le schermate di questa pagina sono realizzate con dati di esempio.
Registro dei messaggi. Filtra per canale, stato, destinatario o per il tuo riferimento, e apri qualsiasi messaggio per vederne la cronologia degli stati e l’importo addebitato.
Fatturazione. Ricarica il portafoglio, acquista pacchetti, imposta la ricarica automatica e scarica le ricevute. I crediti dei pacchetti mostrano quanto resta e quando scade.

Prezzi

Paga a messaggio oppure acquista messaggi in blocco

Ricarica un portafoglio prepagato a partire da 10 $ e paga il prezzo a messaggio di ogni canale, oppure acquista un pacchetto di crediti messaggio per i volumi sui canali più costosi.

Tutti i prezzi

10K messaggi

8 $

0,0008 $ a messaggio

  • 10.000 messaggi in uscita
  • Valido 3 mesi dall’acquisto
  • Valido su tutti i tipi di canale
Inizia con 10K

100K messaggi

In evidenza

60 $

0,0006 $ a messaggio

  • 100.000 messaggi in uscita
  • Valido 6 mesi dall’acquisto
  • Valido su tutti i tipi di canale
Inizia con 100K

1 Mln messaggi

400 $

0,0004 $ a messaggio

  • 1.000.000 messaggi in uscita
  • Valido 12 mesi dall’acquisto
  • Valido su tutti i tipi di canale
Inizia con 1 Mln

A consumo

Prezzo a consumo per messaggio in uscita per tipo di canale, in dollari statunitensi
CanaleA messaggio
WhatsApp Business0,001 $
Telegram0,0003 $
SMS0,0005 $
SMS OTP0,0005 $
Messenger0,0005 $
Instagram0,0005 $
TikTok0,0005 $

Che cosa copre il prezzo

  • AddebitatiI messaggi in uscita accettati dall’API, nel momento in cui vengono accettati.
  • GratuitiMessaggi in entrata, messaggi in modalità di test, webhook e console.
  • RimborsatiTutti i messaggi che terminano come non riusciti: il rimborso torna al pacchetto o al portafoglio di provenienza.
  • A parteLe tariffe che Meta, gli operatori o altri fornitori applicano per il canale stesso.

Esperienza per gli sviluppatori

Pensato per essere integrato una volta e poi dimenticato

Webhook firmati, nuovi tentativi sicuri, una sandbox che si comporta come la produzione ed errori su cui puoi basare la logica del tuo codice.

Riferimento API

Webhook che puoi verificare

Ogni consegna è firmata con HMAC-SHA256 calcolato sul timestamp e sul corpo non elaborato, nell’intestazione OmniMessage-Signature. Rispondi con un qualsiasi 2xx entro 10 secondi. Le consegne non riuscite vengono ritentate otto volte con backoff, da 30 secondi fino a 24 ore.

verify-signature.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// header is "t=<unix seconds>,v1=<hex hmac-sha256>"
export function verifySignature(rawBody, header, secret) {
  const parts = header.split(',').map((part) => part.split('='));
  const { t, v1 = '' } = Object.fromEntries(parts);

  const expected = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const matches =
    v1.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected));

  return fresh && matches;
}
Evento message.delivered
{
  "id": "evt_8Kd2pQ7wN4xB1zR6mT3c",
  "object": "event",
  "type": "message.delivered",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "object": "message",
      "status": "delivered",
      "reference": "order-1042",
      "delivered_at": "2026-10-05T09:30:02.871Z"
    }
  }
}

Una modalità di test che non costa nulla

Le chiavi di test usano canali sandbox integrati, quindi non c’è nulla da collegare. Le ultime cifre del destinatario determinano l’esito simulato, e i tuoi webhook scattano come farebbero in produzione.

Richiesta sandbox, termina come letto
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_test_whatsapp",
    "to": "+971501230002",
    "type": "text",
    "text": { "body": "Hello from the sandbox" }
  }'

Errori con un tipo e un codice

Ogni risposta non 2xx ha lo stesso corpo: un type per la classe di errore, un code stabile su cui basare la logica, il param responsabile quando esiste e un request_id per l’assistenza.

402 Payment Required
{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Not enough wallet balance or package credits.",
    "request_id": "req_5Vn1cH8jL3qW6yD9sF2k",
    "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance"
  }
}

  • POST idempotenti

    Invia un’intestazione Idempotency-Key: un nuovo tentativo entro 24 ore restituisce la risposta memorizzata con Idempotent-Replayed: true, senza inviare né addebitare due volte.

  • Limiti prevedibili

    100 richieste al secondo per chiave su POST /v1/messages, 20 altrove. Ogni risposta include RateLimit-Remaining, e un 429 include Retry-After.

  • Invio in batch

    POST /v1/messages/batch accetta fino a 100 messaggi. Ogni elemento viene accettato, rifiutato e addebitato singolarmente, e la risposta 207 li riporta per indice.

  • Chiavi con ambiti limitati

    Assegna a ogni chiave solo gli ambiti di cui ha bisogno, come messages:write o billing:read, e limitala a un elenco di indirizzi IP consentiti.

Domande

Prima di integrare

Le risposte brevi. Quelle lunghe sono nella documentazione.

Mi servono un numero WhatsApp, un bot o un numero SMS miei?

Sì. OmniMessage è un gateway a cui porti i tuoi canali: colleghi il tuo numero WhatsApp Cloud API, il tuo bot Telegram, il tuo numero Twilio o il tuo account social, e ne resti il titolare. La pagina dei canali elenca che cosa serve per ogni tipo.

Che cosa mi viene addebitato esattamente?

Un addebito per ogni messaggio in uscita accettato dall’API: un credito di un pacchetto, se ne hai, altrimenti il prezzo a messaggio del tipo di canale, prelevato dal portafoglio. I messaggi in entrata e quelli in modalità di test sono gratuiti, e un messaggio che termina come non riuscito viene rimborsato automaticamente.

Le tariffe di Meta, degli operatori o dei fornitori sono incluse?

No. La tariffa del gateway copre l’API, il tracciamento delle consegne, i webhook e la console. Le tariffe che Meta, Twilio o un altro fornitore applicano per il canale stesso restano tra te e quel fornitore.

Come faccio a fare test senza inviare messaggi reali?

Usa una chiave che inizia con om_test_. Ogni account ha un canale sandbox per tipo, ad esempio ch_test_whatsapp. Nulla viene consegnato o addebitato e gli stati sono simulati: un destinatario che termina con 0000 non riesce, con 0001 resta inviato, con 0002 viene anche letto, e in tutti gli altri casi il messaggio viene consegnato entro circa due secondi.

Che cosa succede quando il saldo si esaurisce?

L’API risponde 402 insufficient_balance e nulla viene messo in coda, quindi non ti ritroverai mai con un debito a posteriori. Puoi iscriverti all’evento balance.low oppure attivare la ricarica automatica per ricaricare il portafoglio quando scende sotto una soglia scelta da te.

Mi serve un SDK?

No. L’API è JSON su HTTPS con autenticazione bearer, quindi va bene qualsiasi client HTTP. La documentazione contiene esempi in cURL, Node, Python e PHP.

Invia oggi il tuo primo messaggio in modalità di test

Crea un account, copia una chiave di test e chiama l’API prima ancora di collegare un canale. Ogni nuovo account parte con 100 messaggi gratuiti.

Ottieni una chiave APILeggi la documentazione