Ga naar de inhoud
On a Message

Voor developers

Bouw klantberichten in je eigen software

Gebruik één API voor berichten via verschillende communicatiekanalen. Ontvang nieuwe gesprekken en statuswijzigingen via webhooks en toon de inbox binnen je eigen software.

Toegang aanvragen

In één oogopslag

Een request, een webhook en een ingebedde inbox. Zo ziet een integratie eruit.

Voorbeeld van een API-request, een webhook-event en een ingebedde inbox in andere software.

Voorbeeld: POST /messages
curl -X POST https://onamessage.app/api/v1/messages \
  -H "Authorization: Bearer $ON_A_MESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "contact_1042",
    "type": "text",
    "content": {
      "text": "Je bijgewerkte offerte staat voor je klaar."
    },
    "client_message_id": "quote-update-1042-v1",
    "tags": ["offerte", "update"],
    "valid_until": "2026-10-11T18:00:00Z"
  }'
Webhook: message.received
{
  "id": "evt_demo_01J9",
  "type": "message.received",
  "created_at": "2026-10-11T09:42:00Z",
  "account_id": "acc_demo",
  "data": {
    "message_id": "msg_demo_731",
    "channel": "instagram",
    "contact_id": "contact_731",
    "direction": "inbound",
    "content": {
      "type": "text",
      "text": "Waar vind ik mijn ticket?"
    }
  }
}

Berichten

Sessie: 1 account
Kan de factuur opnieuw worden gestuurd?
Natuurlijk. Ik stuur de factuur direct opnieuw.

Voorbeeldweergave met fictieve klantgegevens.

API-basis

Een REST-API is een vaste set webadressen waarmee jouw server berichten kan versturen en ophalen. Alle verzoeken gaan naar dezelfde basis-URL.

Base URL

https://onamessage.app/api/v1
  • client_message_id maakt herhaalde requests veilig. Stuur je hetzelfde verzoek twee keer, dan wordt het bericht maar één keer verstuurd.
  • Een bericht na valid_until wordt niet alsnog verstuurd. Zo gaat er geen herinnering uit die niet meer klopt.
  • Het veld channel geeft aan via welk kanaal het bericht gaat: whatsapp, email, instagram of messenger.
  • In de voorbeelden staan geen echte telefoonnummers. Je verwijst naar een contact-ID.
  • De voorbeeldsleutel is een variabele. We publiceren geen werkende API-key.

Een bericht versturen

POST /messages
curl -X POST https://onamessage.app/api/v1/messages \
  -H "Authorization: Bearer $ON_A_MESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "contact_1042",
    "type": "text",
    "content": {
      "text": "Je bijgewerkte offerte staat voor je klaar."
    },
    "client_message_id": "quote-update-1042-v1",
    "tags": ["offerte", "update"],
    "valid_until": "2026-10-11T18:00:00Z"
  }'

Webhooks

Een webhook is een melding die On a Message naar jouw server stuurt zodra er iets gebeurt. Dit zijn de events.

  • conversation.created

    Er is een nieuw gesprek gestart, via welk kanaal dan ook.

  • message.received

    Er is een nieuw bericht binnengekomen.

  • message.sent

    Er is een bericht verstuurd.

  • message.status

    De status van een verstuurd bericht is veranderd.

  • conversation.assigned

    Een gesprek is aan een teamlid toegewezen.

  • ai.reply.created

    De AI-assistent heeft een antwoord gemaakt.

  • ai.handover.requested

    De AI-assistent vraagt een medewerker het gesprek over te nemen.

Eventnamen kunnen bij nieuwe versies van de API wijzigen. Dat melden we vooraf.

Elke uitgaande webhook krijgt een HMAC-handtekening en een unieke event-ID. Met de handtekening controleer je dat de melding echt van On a Message komt. Met de event-ID voorkom je dat je dezelfde melding twee keer verwerkt. De exacte headers staan in de documentatie die we met je delen.

Webhook: message.received
{
  "id": "evt_demo_01J9",
  "type": "message.received",
  "created_at": "2026-10-11T09:42:00Z",
  "account_id": "acc_demo",
  "data": {
    "message_id": "msg_demo_731",
    "channel": "instagram",
    "contact_id": "contact_731",
    "direction": "inbound",
    "content": {
      "type": "text",
      "text": "Waar vind ik mijn ticket?"
    }
  }
}

Embedded toegang in vier stappen

Je gebruiker opent de inbox vanuit jouw product. Zonder tweede login en zonder iframe.

  1. Stap 1

    Sessie aanvragen

    De server van de partner vraagt met een API-key een kortlevende sessie aan.

  2. Stap 2

    Veilige redirect

    De gebruiker wordt via een veilige redirect naar de juiste omgeving gebracht.

  3. Stap 3

    Rol bepaalt toegang

    De rol uit de aanvraag bepaalt de toegestane handelingen.

  4. Stap 4

    Begrensd en tijdelijk

    De sessie is begrensd tot één account en verloopt automatisch.

Voor partners

Partneraccounts worden in overleg met On a Roll ingericht. Afspraken over onboarding, ondersteuning en facturatie maken we per partner. Facturatie kan rechtstreeks of via de partner verlopen.

Praat met ons