AsyncAPI Specification
asyncapi: 2.6.0
info:
title: Dialpad Webhook Events API
version: "1.0.0"
description: |
AsyncAPI specification modeling Dialpad's webhook event subscriptions.
Dialpad delivers events as HTTP POST requests to a customer-supplied
hook_url. When a webhook is created with a `secret`, payloads are JWT
encoded (HS256); otherwise payloads are delivered as plain JSON.
Subscription types modeled here:
- Call Event Subscription (call.*)
- SMS Event Subscription (message.*)
- Agent Status Event Subscription (agent_status.*)
- Contact Event Subscription (contact.*)
- Change Log Event Subscription (change_log.*)
Sources: https://developers.dialpad.com (llms.txt + event docs).
contact:
name: Dialpad Developers
url: https://developers.dialpad.com
license:
name: Proprietary
url: https://www.dialpad.com/legal/
defaultContentType: application/json
servers:
consumer:
url: "{hook_url}"
protocol: https
description: |
Customer-supplied webhook endpoint registered via
POST /api/v2/webhooks (field `hook_url`). One webhook can be shared
across multiple event subscriptions.
variables:
hook_url:
description: The fully-qualified HTTPS URL Dialpad will POST events to.
default: https://example.com/dialpad/webhook
channels:
call-events:
description: |
Call lifecycle events delivered to the registered webhook when a Call
Event Subscription matches. Subscription is managed via
POST /api/v2/subscriptions/call.
bindings:
http:
type: request
method: POST
subscribe:
operationId: receiveCallEvent
summary: Receive a Dialpad call event.
message:
$ref: '#/components/messages/CallEvent'
sms-events:
description: |
SMS / MMS message events delivered when an SMS Event Subscription
matches. Subscription is managed via POST /api/v2/subscriptions/sms.
bindings:
http:
type: request
method: POST
subscribe:
operationId: receiveSmsEvent
summary: Receive a Dialpad SMS / MMS event.
message:
$ref: '#/components/messages/SmsEvent'
agent-status-events:
description: |
Call-center agent status change events delivered when an Agent Status
Event Subscription matches. Subscription is managed via
POST /api/v2/subscriptions/agent_status.
bindings:
http:
type: request
method: POST
subscribe:
operationId: receiveAgentStatusEvent
summary: Receive a Dialpad agent status change event.
message:
$ref: '#/components/messages/AgentStatusEvent'
contact-events:
description: |
Contact create / update / delete events delivered when a Contact Event
Subscription matches. Subscription is managed via
POST /api/v2/subscriptions/contact.
bindings:
http:
type: request
method: POST
subscribe:
operationId: receiveContactEvent
summary: Receive a Dialpad contact event.
message:
$ref: '#/components/messages/ContactEvent'
change-log-events:
description: |
Change log events tracking modifications across the Dialpad company
environment. Subscription is managed via
POST /api/v2/subscriptions/changelog. Requires the `change_log` OAuth
scope.
bindings:
http:
type: request
method: POST
subscribe:
operationId: receiveChangeLogEvent
summary: Receive a Dialpad change log event.
message:
$ref: '#/components/messages/ChangeLogEvent'
components:
messages:
CallEvent:
name: CallEvent
title: Call Event
summary: Notifies of a state change in a Dialpad call.
contentType: application/json
payload:
$ref: '#/components/schemas/CallEventPayload'
SmsEvent:
name: SmsEvent
title: SMS / MMS Event
summary: Notifies of an SMS or MMS message event.
contentType: application/json
payload:
$ref: '#/components/schemas/SmsEventPayload'
AgentStatusEvent:
name: AgentStatusEvent
title: Agent Status Event
summary: Notifies of a call-center agent status change.
contentType: application/json
payload:
$ref: '#/components/schemas/AgentStatusEventPayload'
ContactEvent:
name: ContactEvent
title: Contact Event
summary: Notifies of a contact created, updated, or deleted.
contentType: application/json
payload:
$ref: '#/components/schemas/ContactEventPayload'
ChangeLogEvent:
name: ChangeLogEvent
title: Change Log Event
summary: Notifies of a configuration / administrative change in Dialpad.
contentType: application/json
payload:
$ref: '#/components/schemas/ChangeLogEventPayload'
schemas:
Target:
type: object
description: A Dialpad entity (user, group, room, etc.) involved in an event.
properties:
id:
type: integer
format: int64
type:
type: string
enum:
- callcenter
- callrouter
- channel
- coachinggroup
- coachingteam
- department
- office
- room
- staffgroup
- unknown
- user
name:
type: string
email:
type: string
phone:
type: string
Contact:
type: object
description: An external contact party in an event.
properties:
id:
type: string
type:
type: string
enum:
- google
- local
- microsoft
- shared
- all
first_name:
type: string
last_name:
type: string
display_name:
type: string
phones:
type: array
items:
type: string
primary_phone:
type: string
emails:
type: array
items:
type: string
primary_email:
type: string
company_name:
type: string
job_title:
type: string
urls:
type: array
items:
type: string
trunk_group:
type: string
extension:
type: string
CallEventPayload:
type: object
description: |
Payload delivered for call lifecycle state changes. Fields documented
at https://developers.dialpad.com/docs/call-events.
properties:
call_id:
type: integer
format: int64
master_call_id:
type: integer
format: int64
operator_call_id:
type: integer
format: int64
entry_point_call_id:
type: integer
format: int64
state:
type: string
description: Current call state.
enum:
- calling
- ringing
- preanswer
- connected
- merged
- hold
- parked
- voicemail
- voicemail_uploaded
- transcription
- hangup
- missed
- recording
- call_transcription
- dispositions
- recap_summary
- recap_outcome
- recap_purposes
- recap_action_items
- ai_playbook
direction:
type: string
enum:
- inbound
- outbound
target:
$ref: '#/components/schemas/Target'
contact:
$ref: '#/components/schemas/Contact'
date_started:
type: integer
format: int64
description: Unix timestamp (ms).
date_connected:
type: integer
format: int64
date_ended:
type: integer
format: int64
duration:
type: integer
description: Call duration.
event_timestamp:
type: integer
format: int64
SmsEventPayload:
type: object
description: |
Payload delivered for SMS / MMS message events.
Fields documented at https://developers.dialpad.com/docs/sms-events.
properties:
id:
type: integer
format: int64
description: Unique numeric identifier for the message.
created_date:
type: integer
format: int64
description: Unix timestamp of message creation.
direction:
type: string
enum:
- inbound
- outbound
target:
$ref: '#/components/schemas/Target'
contact:
$ref: '#/components/schemas/Contact'
sender_id:
type: integer
format: int64
description: User ID who sent the message in group scenarios.
from_number:
type: string
description: E.164 phone number of sender.
to_number:
type: array
items:
type: string
description: E.164 phone numbers of receivers.
mms:
type: boolean
text:
type: string
description: |
SMS content or, for MMS, the URL of the media. Requires
appropriate OAuth scope to be included.
message_status:
type: string
enum:
- sent
- failed
- pending
- delivered
- undelivered
message_delivery_result:
type: string
description: Fine-grained delivery outcome.
AgentStatusEventPayload:
type: object
description: |
Payload delivered for call-center agent status changes.
Fields documented at https://developers.dialpad.com/docs/agent-status-events.
properties:
availability_status:
type: boolean
description: True when agent is available (not DND, not on a call).
on_duty_status:
type: string
enum:
- Available
- Unavailable
- Occupied
- Wrapup
- Busy
on_duty_status_reason:
type: string
description: Custom reason text supplied by the agent.
call_center_ids:
type: array
items:
type: integer
format: int64
powerdialer_mode:
type: boolean
powerdialer_session:
type: string
target:
$ref: '#/components/schemas/Target'
date:
type: integer
format: int64
description: Unix timestamp (ms) when status changed.
event_timestamp:
type: integer
format: int64
description: Unix timestamp (ms) when webhook was generated.
ContactEventPayload:
type: object
description: |
Payload delivered for contact created / updated / deleted events.
Fields documented at https://developers.dialpad.com/docs/contact-events.
properties:
event:
type: string
enum:
- Created
- Updated
- Deleted
contact:
$ref: '#/components/schemas/Contact'
ChangeLogEventPayload:
type: object
description: |
Payload delivered for change log events.
Fields documented at https://developers.dialpad.com/docs/change-log-events.
properties:
date:
type: integer
format: int64
description: Unix timestamp (ms UTC) of the change.
action:
type: string
description: Human-readable code (e.g. `updated_ivr`, `operator_removed`).
note:
type: string
description: Contextual text explanation. Formatting not standardized.
additional_data:
type: object
description: Optional details about what changed. Formatting not standardized.
additionalProperties: true
target:
$ref: '#/components/schemas/Target'
changed_by:
type: object
description: |
Source of the change. Contains name, id, and type for company
employees; redacted for Dialpad-initiated changes.
properties:
id:
type: integer
format: int64
name:
type: string
type:
type: string