Siirry sisältöön
OmniMessage

Viestiyhdyskäytävän API

Yksi API kaikkiin viestikanaviin

Lähetä WhatsApp Business-, SMS-, Telegram-, Messenger-, Instagram- ja TikTok-viestejä yhden REST-päätepisteen kautta. Ennakkoon maksettu, laskutus lähtevän viestin mukaan, mukana toimituswebhookit ja testitila.

Hanki API-avainLue dokumentaatio
Alkaen
0,0003 $
lähtevää viestiä kohden
Rekisteröityessä
100
ilmaista viestiä
Sitoutuminen
Ei lainkaan
ennakkomaksu, ei sopimusta
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
}
  • Kanavatyypit7 yhden päätepisteen takana
  • Viestityypit9, tekstistä interaktiivisiin luetteloihin
  • Hinta alkaen0,0003 $ lähtevää viestiä kohden
  • Pyyntöraja100 pyyntöä sekunnissa avainta kohden
  • Erän kokoEnintään 100 viestiä pyyntöä kohden
  • Webhookien uudelleenyritykset8, kasvavin välein 30 sekunnista 24 tuntiin
  • Idempotenssi-ikkuna24 tuntia
  • TestitilaMaksuton, kanavaa ei tarvita
  • Epäonnistuneet viestitHyvitetään automaattisesti
  • Saapuvat viestitMaksuttomia

Kanavat

Seitsemän kanavatyyppiä, yksi pyyntömuoto

Yhdistä lähettäjät, jotka sinulla jo on. Jokaisesta tulee kanavatunniste, jonka välität samalle päätepisteelle, ja jokainen raportoi takaisin samat tilat.

Vertaile kanavia

Näin se toimii

Rekisteröitymisestä toimitettuun viestiin neljässä vaiheessa

Ei myyntipuheluita eikä vähimmäissitoumusta. Voit tehdä ensimmäisen API-kutsusi testitilassa minuutin kuluttua tilin luomisesta.

  1. Vaihe 01

    Luo tili

    Rekisteröidy, vahvista sähköpostiosoitteesi ja luo API-avain konsolissa. Testiavaimet toimivat heti, ennen kuin yhtään kanavaa on yhdistetty.

  2. Vaihe 02

    Yhdistä kanava

    Kirjaudu konsolissa Facebookilla tai TikTokilla, niin voit yhdistää WhatsApp-numeron, sivun tai yritystilin. Lisää Telegram-botti tai Twilio-numero tunnistetiedoillaan joko konsolissa tai kutsulla POST /v1/channels.

  3. Vaihe 03

    Lähetä yhden päätepisteen kautta

    POST /v1/messages ottaa vastaan kanavatunnisteen, vastaanottajan ja tyypitetyn sisältöobjektin. Pyyntömuoto on sama jokaisessa kanavassa.

  4. Vaihe 04

    Seuraa jokaista toimitusta

    Allekirjoitetut webhookit kertovat, kun viesti on lähetetty, toimitettu, luettu tai epäonnistunut. Sama historia löytyy konsolista ja kutsulla GET /v1/messages.

Viestityypit

Mitä lähetät, sen vastaanottaja näkee

Jokaisella viestillä on tyyppi ja sisältöobjekti tyypin nimisen avaimen alla. Valitse tyyppi, niin näet pyynnön rungon ja sen tuottaman viestin rinnakkain.

Kaikki viestityypit
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "Tilauksesi #1042 on lähetetty. Seuraa sitä osoitteessa https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}

Pelkkä teksti, jonka jokainen kanavatyyppi hyväksyy. Aseta preview_url, niin kanava näyttää linkin esikatselun.

KanavatWhatsApp Business, SMS, SMS OTP, Telegram, Messenger, Instagram ja TikTok

Konsoli

Konsoli kaikelle, mikä ei ole koodia

Luo avaimia, yhdistä kanavia, hae viestilokista, toista webhook-toimituksia ja hallitse laskutusta. Kaikki, minkä konsoli näyttää, on saatavilla myös API:n kautta.

Yleiskatsaus. Lompakon saldo, jäljellä olevat pakettikrediitit ja viimeisten 30 päivän lähtevä volyymi tili- ja tilakohtaisesti. Tämän sivun näkymät on piirretty esimerkkidatalla.
Viestiloki. Suodata kanavan, tilan, vastaanottajan tai oman viitteesi mukaan ja avaa mikä tahansa viesti nähdäksesi sen tilahistorian ja veloituksen.
Laskutus. Lataa lompakkoon saldoa, osta paketteja, ota automaattinen lataus käyttöön ja lataa kuitit. Pakettikrediiteistä näet, paljonko on jäljellä ja milloin ne vanhenevat.

Hinnoittelu

Maksa viestikohtaisesti tai osta viestejä kerralla

Lataa ennakkoon maksettuun lompakkoon saldoa alkaen 10 $ ja maksa kunkin kanavan viestikohtainen hinta, tai osta viestikrediittipaketti kalleimpien kanaviesi volyymia varten.

Koko hinnasto

10 t. viestiä

8 $

0,0008 $ / viesti

  • 10 000 lähtevää viestiä
  • Voimassa 3 kuukautta ostohetkestä
  • Käy kaikissa kanavatyypeissä
Aloita paketilla 10 t.

100 t. viestiä

Suositeltu

60 $

0,0006 $ / viesti

  • 100 000 lähtevää viestiä
  • Voimassa 6 kuukautta ostohetkestä
  • Käy kaikissa kanavatyypeissä
Aloita paketilla 100 t.

1 milj. viestiä

400 $

0,0004 $ / viesti

  • 1 000 000 lähtevää viestiä
  • Voimassa 12 kuukautta ostohetkestä
  • Käy kaikissa kanavatyypeissä
Aloita paketilla 1 milj.

Käytön mukaan

Käytön mukainen hinta lähtevää viestiä kohden kanavatyypeittäin, Yhdysvaltain dollareina
KanavaViestiä kohden
WhatsApp Business0,001 $
Telegram0,0003 $
SMS0,0005 $
SMS OTP0,0005 $
Messenger0,0005 $
Instagram0,0005 $
TikTok0,0005 $

Mitä hinta kattaa

  • VeloitetaanAPI:n hyväksymät lähtevät viestit sillä hetkellä, kun ne hyväksytään.
  • MaksutontaSaapuvat viestit, testitilan viestit, webhookit ja konsoli.
  • HyvitetäänJokainen epäonnistuneeksi päätyvä viesti siihen pakettiin tai lompakkoon, josta se veloitettiin.
  • ErikseenMaksut, jotka Meta, operaattorit tai muut palveluntarjoajat perivät itse kanavasta.

Kehittäjäkokemus

Tehty integroitavaksi kerran ja jätettäväksi rauhaan

Allekirjoitetut webhookit, turvalliset uudelleenyritykset, tuotannon tavoin toimiva hiekkalaatikko ja virheet, joiden mukaan voit haarauttaa koodisi.

API-viite

Webhookit, jotka voit todentaa

Jokainen toimitus allekirjoitetaan HMAC-SHA256:lla aikaleiman ja käsittelemättömän rungon yli, ja allekirjoitus on OmniMessage-Signature-otsakkeessa. Vastaa millä tahansa 2xx-koodilla 10 sekunnin kuluessa. Epäonnistuneita toimituksia yritetään uudelleen kahdeksan kertaa kasvavin välein, 30 sekunnista 24 tuntiin.

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;
}
Tapahtuma 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"
    }
  }
}

Testitila, joka ei maksa mitään

Testiavaimet käyttävät sisäänrakennettuja hiekkalaatikkokanavia, joten mitään ei tarvitse yhdistää. Vastaanottajan viimeiset numerot ratkaisevat simuloidun lopputuloksen, ja webhookisi laukeavat kuten tuotannossa.

Hiekkalaatikkopyyntö, päätyy luetuksi
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" }
  }'

Virheet, joilla on tyyppi ja koodi

Jokaisessa muussa kuin 2xx-vastauksessa on sama runko: virheluokan kertova type, vakaa code haarautumista varten, virheen aiheuttanut param, jos sellainen on, ja request_id tukea varten.

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"
  }
}

  • Idempotentit POST-pyynnöt

    Lähetä Idempotency-Key-otsake, niin 24 tunnin kuluessa tehty uudelleenyritys palauttaa tallennetun vastauksen otsakkeella Idempotent-Replayed: true lähettämättä tai veloittamatta kahdesti.

  • Ennustettavat rajat

    100 pyyntöä sekunnissa avainta kohden päätepisteessä POST /v1/messages, muualla 20. Jokaisessa vastauksessa on RateLimit-Remaining, ja 429-vastauksessa Retry-After.

  • Erälähetys

    POST /v1/messages/batch hyväksyy enintään 100 viestiä. Jokainen viesti hyväksytään, hylätään ja veloitetaan erikseen, ja 207-vastaus raportoi ne indeksin mukaan.

  • Rajatut avaimet

    Anna kullekin avaimelle vain sen tarvitsemat käyttöoikeudet, kuten messages:write tai billing:read, ja rajoita se sallittujen IP-osoitteiden luetteloon.

Kysymyksiä

Ennen kuin integroit

Tässä lyhyet vastaukset. Pitkät löytyvät dokumentaatiosta.

Tarvitsenko oman WhatsApp-numeron, botin tai SMS-numeron?

Kyllä. OmniMessage on yhdyskäytävä, johon tuot omat kanavasi: yhdistät oman WhatsApp Cloud API -numerosi, Telegram-bottisi, Twilio-numerosi tai sometilisi, ja ne pysyvät sinun omistuksessasi. Kanavasivulla kerrotaan, mitä kukin tyyppi vaatii.

Mistä minua tarkalleen veloitetaan?

Yksi veloitus jokaisesta lähtevästä viestistä, jonka API hyväksyy: pakettikrediitti, jos sinulla on sellainen, muuten kanavatyypin viestikohtainen hinta lompakostasi. Saapuvat viestit ja testitilan viestit ovat maksuttomia, ja epäonnistuneeksi päätyvä viesti hyvitetään automaattisesti.

Sisältyvätkö Metan, operaattoreiden tai palveluntarjoajien maksut hintaan?

Eivät. Yhdyskäytävämaksu kattaa API:n, toimitusseurannan, webhookit ja konsolin. Maksut, jotka Meta, Twilio tai muu palveluntarjoaja perii itse kanavasta, jäävät sinun ja kyseisen palveluntarjoajan välisiksi.

Miten testaan lähettämättä oikeita viestejä?

Käytä avainta, joka alkaa merkeillä om_test_. Jokaisella tilillä on hiekkalaatikkokanava kutakin tyyppiä varten, esimerkiksi ch_test_whatsapp. Mitään ei toimiteta eikä laskuteta, ja tilat ovat simuloituja: numeroihin 0000 päättyvä vastaanottaja epäonnistuu, 0001 jää lähetetyksi, 0002 merkitään myös luetuksi, ja kaikki muut toimitetaan noin kahdessa sekunnissa.

Mitä tapahtuu, kun saldoni loppuu?

API vastaa 402 insufficient_balance eikä mitään lisätä jonoon, joten et koskaan jää jälkikäteen velkaa. Voit tilata balance.low-tapahtuman tai ottaa käyttöön automaattisen latauksen, joka lataa lompakkoa, kun saldo laskee valitsemasi alarajan alle.

Tarvitsenko SDK:n?

Et. API on JSONia HTTPS:n yli bearer-todennuksella, joten mikä tahansa HTTP-asiakas käy. Dokumentaatiossa on esimerkit cURLilla, Nodella, Pythonilla ja PHP:llä.

Lähetä ensimmäinen viestisi testitilassa jo tänään

Luo tili, kopioi testiavain ja kutsu API:a ennen kuin yhdistät ainuttakaan kanavaa. Jokainen uusi tili saa alkuun 100 ilmaista viestiä.

Hanki API-avainLue dokumentaatio