---
title: "Wait for an event"
method: POST
path: "/api/v1/events/wait"
tags: ["events"]
---

# Wait for an event

`POST /api/v1/events/wait`

Long-polls until the next event of `eventType` arrives on the account
(optionally matching `filters`/`regexFilters`), or until `timeout` seconds
elapse. Useful for one-shot waits such as receiving an inbound SMS code.
For a continuous stream, use Open an event stream instead.

## Headers

- `Authorization` string, required

## Request body

- object
  - `eventType` string, required — Event type to wait for.
  - `filters` object — Exact-match on top-level event fields.
  - `regexFilters` object — Regex-match on top-level event fields.
  - `timeout` integer — Max seconds to wait.

## Response `200`

The matching event.

- EventsWaitForEventResponse200
  - `event` union — An account event. Every event shares one envelope — `id`, `object` ("event"), `type`, `version`, `createdAt`, `relatedObject` — and a `data` payload whose shape the `type` selects. Field names are camelCase. Today: `message.received` (an inbound SMS), `call.ended` (a call finished), and `call.transcribed` (a call's transcript is ready).
    - object — message.received variant
      - `type` 'message.received', required
      - `id` string, required — Stable event id (also the webhook X-Dial-Event-ID).
      - `object` 'event', required
      - `version` integer, required
      - `createdAt` string, date-time, required
      - `relatedObject` RelatedObject, required — A pointer to the REST resource this event concerns. `url` is the get-by-id path when one exists (calls), or null when it does not yet (messages have no get-by-id endpoint).
        - `id` string, required
        - `type` 'call' | 'message', required
        - `url` string, nullable, required
      - `data` MessageReceivedEventData, required
        - `messageId` string, required — The Dial message id (matches `Message.id`).
        - `from` string, required
        - `to` string, required
        - `channel` 'sms' | 'imessage' | 'rcs' | 'unknown', required — The channel the inbound message arrived on: `sms`, `imessage`, or `rcs` (`unknown` when the channel can't be determined).
        - `body` string, required
        - `source` 'external' | 'internal', required — `external` — delivered by a real carrier via the inbound webhook. `internal` — synthesized by Dial itself (e.g. dashboard test tools); the row is real but no SMS was sent over the wire.
    - object — call.ended variant
      - `type` 'call.ended', required
      - `id` string, required — Stable event id (also the webhook X-Dial-Event-ID).
      - `object` 'event', required
      - `version` integer, required
      - `createdAt` string, date-time, required
      - `relatedObject` RelatedObject, required — A pointer to the REST resource this event concerns. `url` is the get-by-id path when one exists (calls), or null when it does not yet (messages have no get-by-id endpoint).
        - `id` string, required
        - `type` 'call' | 'message', required
        - `url` string, nullable, required
      - `data` CallEndedEventData, required
        - `callId` string, required — The Dial call id (matches `Call.id`).
        - `from` string, required
        - `to` string, required
        - `direction` 'inbound' | 'outbound', required
        - `durationSeconds` integer, nullable, required
        - `status` 'completed' | 'busy' | 'no-answer' | 'failed' | 'canceled', required — The call's terminal status.
        - `canceled` boolean, required — True if the call was cancelled before it ended (dashboard terminate or cancel API) — even if `status` is `completed`.
        - `transcriptAvailable` boolean, required — Whether a transcript exists. When true, a `call.transcribed` event follows once the transcript is processed.
    - object — call.transcribed variant
      - `type` 'call.transcribed', required
      - `id` string, required — Stable event id (also the webhook X-Dial-Event-ID).
      - `object` 'event', required
      - `version` integer, required
      - `createdAt` string, date-time, required
      - `relatedObject` RelatedObject, required — A pointer to the REST resource this event concerns. `url` is the get-by-id path when one exists (calls), or null when it does not yet (messages have no get-by-id endpoint).
        - `id` string, required
        - `type` 'call' | 'message', required
        - `url` string, nullable, required
      - `data` CallTranscribedEventData, required
        - `callId` string, required — The Dial call id (matches `Call.id`).

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `408` — No matching event arrived within the timeout.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)