asyncapi: 3.0.0
info:
  title: AgentPhone Webhooks
  version: 1.0.0
  description: >-
    Event surface AgentPhone delivers to a project-level or per-agent webhook
    URL. Generated by the API Evangelist enrichment pipeline from the published
    webhook documentation (https://docs.agentphone.ai/documentation/guides/webhooks);
    AgentPhone does not publish an AsyncAPI document of its own.
  x-provenance:
    generated: '2026-07-17'
    method: generated
    source: https://docs.agentphone.ai/documentation/guides/webhooks
defaultContentType: application/json
servers:
  webhook:
    host: your-endpoint.example.com
    protocol: https
    description: The consumer HTTPS endpoint registered via POST /v1/webhooks.
channels:
  events:
    address: /
    description: All AgentPhone events POST to the configured webhook URL.
    messages:
      agentMessage:
        $ref: '#/components/messages/AgentMessage'
      agentCallEnded:
        $ref: '#/components/messages/AgentCallEnded'
      agentReaction:
        $ref: '#/components/messages/AgentReaction'
operations:
  receiveEvent:
    action: receive
    channel:
      $ref: '#/channels/events'
    messages:
    - $ref: '#/channels/events/messages/agentMessage'
    - $ref: '#/channels/events/messages/agentCallEnded'
    - $ref: '#/channels/events/messages/agentReaction'
components:
  messages:
    AgentMessage:
      name: agent.message
      title: Inbound SMS/voice message for an agent
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        type: object
        properties:
          event: {type: string, const: agent.message}
          channel: {type: string, enum: [sms, voice]}
          timestamp: {type: string, format: date-time}
          agentId: {type: string}
          data: {type: object}
          conversationState: {type: [object, 'null']}
          recentHistory: {type: array}
    AgentCallEnded:
      name: agent.call_ended
      title: A voice call has ended
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        type: object
        properties:
          event: {type: string, const: agent.call_ended}
          agentId: {type: string}
          timestamp: {type: string, format: date-time}
          data: {type: object}
    AgentReaction:
      name: agent.reaction
      title: A reaction was applied to a message
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        type: object
        properties:
          event: {type: string, const: agent.reaction}
          agentId: {type: string}
          timestamp: {type: string, format: date-time}
          data: {type: object}
  schemas:
    WebhookHeaders:
      type: object
      properties:
        X-Webhook-Signature:
          type: string
          description: HMAC-SHA256 over '{timestamp}.{raw_body}' as sha256=<hex>.
        X-Webhook-ID:
          type: string
          description: Unique delivery ID; use for idempotent processing.