> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Wait for an event

POST https://api.getdial.ai/api/v1/events/wait
Content-Type: application/json

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.


Reference: https://docs.getdial.ai/api-reference/rest-api/events/wait-for-event

## Authentication

- `Authorization` header (bearer token, required) — Your Dial API key, sent as `Authorization: Bearer sk_live_...`

## Request

### Body (application/json)

- `eventType` (string, required) — Event type to wait for.
- `filters` (map from string to any, optional) — Exact-match on top-level event fields.
- `regexFilters` (map from string to any, optional) — Regex-match on top-level event fields.
- `timeout` (integer, optional, default: 30) — Max seconds to wait.

## Response

### 200

The matching event.

- `event` (object, optional) — 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).
  - `type`: `message.received` (message.received)
    - `createdAt` (datetime, required)
    - `data` (object, required)
      - `messageId` (string, required) — The Dial message id (matches `Message.id`).
      - `from` (string, required) — Who sent it. On a group message, the participant who sent it — not the group.
      - `to` (string, required, nullable) — The number it arrived on, and **null when `groupId` is set**: a group message is addressed to the group. Which of your numbers the conversation is on is the message's `phoneNumberId`.
      - `channel` (enum, required) — The channel the inbound message arrived on: `sms`, `imessage`, `rcs`, or `whatsapp` (`unknown` when the channel can't be determined).
        - Allowed values: `sms`, `imessage`, `rcs`, `whatsapp`, `unknown`
      - `body` (string, required)
      - `source` (enum, 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.
        - Allowed values: `external`, `internal`
      - `groupId` (string, optional, nullable) — The group conversation the message belongs to, or null for a one-to-one conversation. A Dial ID (see List groups); filter on it with `filters: { "groupId": "…" }` when waiting for an event.
    - `id` (string, required) — Stable event id (also the webhook X-Dial-Event-ID).
    - `object` (enum, required)
      - Allowed values: `event`
    - `relatedObject` (object, 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` (enum, required)
        - Allowed values: `call`, `message`
      - `url` (string, required, nullable)
    - `version` (integer, required)
  - `type`: `call.ended` (call.ended)
    - `createdAt` (datetime, required)
    - `data` (object, required)
      - `callId` (string, required) — The Dial call id (matches `Call.id`).
      - `from` (string, required)
      - `to` (string, required)
      - `direction` (enum, required)
        - Allowed values: `inbound`, `outbound`
      - `durationSeconds` (integer, required, nullable)
      - `status` (enum, required) — The call's terminal status.
        - Allowed values: `completed`, `busy`, `no-answer`, `failed`, `canceled`
      - `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.
    - `id` (string, required) — Stable event id (also the webhook X-Dial-Event-ID).
    - `object` (enum, required)
      - Allowed values: `event`
    - `relatedObject` (object, 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` (enum, required)
        - Allowed values: `call`, `message`
      - `url` (string, required, nullable)
    - `version` (integer, required)
  - `type`: `call.transcribed` (call.transcribed)
    - `createdAt` (datetime, required)
    - `data` (object, required)
      - `callId` (string, required) — The Dial call id (matches `Call.id`).
    - `id` (string, required) — Stable event id (also the webhook X-Dial-Event-ID).
    - `object` (enum, required)
      - Allowed values: `event`
    - `relatedObject` (object, 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` (enum, required)
        - Allowed values: `call`, `message`
      - `url` (string, required, nullable)
    - `version` (integer, required)

## Examples

**Request**

```json
{
  "eventType": "message.received"
}
```

**Response**

```json
{
  "event": {
    "type": "message.received",
    "createdAt": "2024-01-15T09:30:00Z",
    "data": {
      "messageId": "clxxx",
      "from": "+14155559876",
      "to": "+14155550123",
      "channel": "sms",
      "body": "Your code is 123456",
      "source": "external",
      "groupId": null
    },
    "id": "evt_3f9a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90",
    "object": "event",
    "relatedObject": {
      "id": "clxxx",
      "type": "call",
      "url": "/api/v1/calls/clxxx"
    },
    "version": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.getdial.ai/api/v1/events/wait"

payload = { "eventType": "message.received" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getdial.ai/api/v1/events/wait';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"eventType":"message.received"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdial.ai/api/v1/events/wait"

	payload := strings.NewReader("{\n  \"eventType\": \"message.received\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getdial.ai/api/v1/events/wait")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventType\": \"message.received\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getdial.ai/api/v1/events/wait")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventType\": \"message.received\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getdial.ai/api/v1/events/wait', [
  'body' => '{
  "eventType": "message.received"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getdial.ai/api/v1/events/wait");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"eventType\": \"message.received\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["eventType": "message.received"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getdial.ai/api/v1/events/wait")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```