Event Types#

Complete reference of all built-in event types in Outeract.

Quick Reference#

| Event Type | Category | Required Fields | Description | |------------|----------|-----------------|-------------| | `file.inbound` | file | `file_id` | Built-in schema for file.inbound events | | `link_code.activation` | link_code | `link_code_event_id` | Built-in schema for link_code.activation events | | `link_code.generated` | link_code | `code` | Built-in schema for link_code.generated events | | `message.inbound` | message | `type`, `message`, `platform` | Built-in schema for message.inbound events | | `message.outbound` | message | `type`, `message`, `platform` | Built-in schema for message.outbound events | | `user.merged` | user | `source_user_id`, `target_user_id` | Built-in schema for user.merged events |

Reserved prefixes:

Message Events#

message.inbound#

Incoming message from a user.

Payload:

{
  "type": "message",
  "message": {
    "text": "Hello!",
    "role": "user",
    "type": "text"
  },
  "platform": "whatsapp",
  "external_message_id": "wamid.xxx",
  "created_at": "2024-01-15T10:30:00Z"
}

Edges:

  • sent_by → Platform User (sender)
  • sent_to → Platform User (system user)
  • attachment → File (if media attached)

message.outbound#

Outgoing message sent to a user.

Payload:

{
  "type": "message",
  "message": {
    "text": "Thank you for contacting us!",
    "role": "assistant",
    "type": "text"
  },
  "platform": "whatsapp",
  "external_message_id": "wamid.xxx",
  "sent_at": "2024-01-15T10:30:00Z"
}

Edges:

  • sent_by → Platform User (system user)
  • sent_to → Platform User (recipient)
  • attachment → File (if media attached)

message.delivered#

Message was delivered to recipient’s device.

Payload:

{
  "status": "delivered",
  "external_message_id": "wamid.xxx",
  "delivered_at": "2024-01-15T10:30:05Z"
}

Origin Event: Links to message.outbound

message.read#

Message was read by recipient.

Payload:

{
  "status": "read",
  "external_message_id": "wamid.xxx",
  "read_at": "2024-01-15T10:31:00Z"
}

Origin Event: Links to message.outbound

message.failed#

Message delivery failed.

Payload:

{
  "status": "failed",
  "external_message_id": "wamid.xxx",
  "failed_at": "2024-01-15T10:30:10Z",
  "error": {
    "code": "RECIPIENT_NOT_FOUND",
    "message": "Phone number not registered on WhatsApp"
  }
}

Origin Event: Links to message.outbound

message.reaction#

Emoji reaction to a message.

Payload:

{
  "reaction": {
    "emoji": "👍",
    "message_id": "wamid.xxx"
  },
  "platform": "whatsapp"
}

Edges:

  • sent_by → Platform User (reactor)
  • reply_to → Event (original message)

A link code was created.

Payload:

{
  "code": "1234-5678-9012-5924",
  "expiry_minutes": 15,
  "max_uses": 1,
  "uses": 0,
  "generated_by_platform_user_id": "pu_abc123"
}

Edges:

  • generated_by → Platform User

A link code was used to link accounts.

Payload:

{
  "code": "1234-5678-9012-5924",
  "source_platform_user_id": "pu_abc123",
  "target_platform_user_id": "pu_xyz789",
  "merged_user_id": "user_merged123"
}

Edges:

  • source → Platform User (code owner)
  • target → Platform User (code redeemer)

User Events#

user.merged#

Two user records were merged.

Payload:

{
  "source_user_id": "user_old123",
  "target_user_id": "user_kept456",
  "merged_platform_users": ["pu_abc123", "pu_xyz789"]
}

Custom Events#

Custom events can use any valid name - no special prefix required.

Naming Rules#

Event type names must:

  • Use lowercase letters, numbers, dots, and underscores only
  • Match the pattern: ^[a-z0-9_.]+$
  • Not use reserved prefixes: message.*, user.*, system.*, link_code.*

Examples#

order.created

{
  "order_id": "order_12345",
  "total": 99.99,
  "currency": "USD",
  "items": [...]
}

payment.completed

{
  "payment_id": "pay_xyz",
  "amount": 99.99,
  "method": "credit_card"
}

support.ticket.opened

{
  "ticket_id": "ticket_123",
  "subject": "Help needed",
  "priority": "high"
}

purchase (single-word names are valid too)

{
  "item": "Premium Plan",
  "amount": 49.99
}

Media Types#

Messages can include different media types:

text#

{
  "type": "text",
  "text": "Hello!"
}

image#

{
  "type": "image",
  "media": {
    "id": "file_xyz",
    "mime_type": "image/jpeg",
    "url": "https://..."
  },
  "caption": "Check this out!"
}

video#

{
  "type": "video",
  "media": {
    "id": "file_xyz",
    "mime_type": "video/mp4",
    "url": "https://..."
  }
}

audio#

{
  "type": "audio",
  "media": {
    "id": "file_xyz",
    "mime_type": "audio/ogg",
    "url": "https://..."
  }
}

document#

{
  "type": "document",
  "media": {
    "id": "file_xyz",
    "mime_type": "application/pdf",
    "filename": "invoice.pdf",
    "url": "https://..."
  }
}

location#

{
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "San Francisco",
    "address": "123 Main St"
  }
}

contact#

{
  "type": "contact",
  "contact": {
    "name": "John Doe",
    "phone": "+14155551234",
    "email": "john@example.com"
  }
}

Querying Events by Type#

Exact Match#

query {
  events(filters: { eventType: { equals: "message.inbound" } }) {
    edges { node { id } }
  }
}

Pattern Match#

query {
  events(filters: { eventType: { contains: "message" } }) {
    edges { node { id eventType } }
  }
}

Multiple Types#

query {
  events(
    filters: {
      eventType: { in: ["message.inbound", "message.outbound"] }
    }
  ) {
    edges { node { id eventType } }
  }
}

Custom Events Only#

query {
  events(filters: { eventType: { startsWith: "custom." } }) {
    edges { node { id eventType payload } }
  }
}
Backward Reference Error Codes Forward