Events

Tell Beamvia when something happens in your system (an order completes, a payment fails, a parcel ships). The event lands in the contact's latest conversation and Beamvia reacts the way you choose.

reaction	What happens
AI	The AI agent wakes up once, reads the event and tells the customer what matters. Falls back to TEAM when a person handles the conversation or AI is unavailable.
TEAM	Only a private note in the inbox for your team. Nothing is sent to the customer.
MESSAGE	Sends your template to the customer right away, no AI cost.

Event data is shown to the AI as external data: HTML is stripped, long text is cut, and instructions inside it are never followed. Events can never confirm a high-risk action for the customer.

Send an event

Requires the event:write scope. Returns 202; delivered is false with a reason when the reaction could not reach the customer.

Scopeevent:write

toobjectrequired

Who the event is about: { "type": "WHATSAPP", "phone" }, { "type": "EMAIL", "address" }, { "type": "TELEGRAM", "userId" } or { "contactId" }.

typestringrequired

Event name, lowercase letters, numbers, _ . - (max 60), e.g. order.completed.

dataobject

Any JSON object, at most 8 KB.

reactionstring

AI (default), TEAM or MESSAGE.

instructionstring

A hint for the AI, e.g. "Share the tracking number". Max 500 characters.

templatestring

Required for MESSAGE. Supports <%= contact.name.first %> and <%= event.field %>.

channelIdstring

Use the conversation on this channel; starts a WhatsApp conversation when there is none yet.

idstring

Idempotency key. Sending the same id again returns the first event instead of a new one.

POSThttps://www.beamvia.com/api/v1/event

curl -X POST "https://www.beamvia.com/api/v1/event" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "order-1042-completed",
    "to": {
      "type": "WHATSAPP",
      "phone": "+6281234567890"
    },
    "type": "order.completed",
    "data": {
      "order": {
        "number": "1042",
        "total": "Rp 250.000",
        "tracking": "JNE123456"
      }
    },
    "instruction": "Tell the customer the order is complete and share the tracking number"
  }'

{
  "status": true,
  "message": "Event received",
  "data": {
    "event": {
      "id": "6650f0c2a1b2c3d4e5f60720"
    },
    "conversationId": "6650f0c2a1b2c3d4e5f60700",
    "delivered": true,
    "reason": null
  }
}