Phonely Webhooks API

asyncapi: 3.0.0
info:
  title: Phonely Webhooks
  version: "1.0.0"
  description: |
    Phonely delivers post-call event data to any HTTPS endpoint configured via
    the "Send Call Data" post-call action in the workflow builder. The event is
    delivered as an HTTP POST with a JSON body containing call metadata, transcript,
    AI analysis (summary, sentiment, key points, action items), follow-up
    indicators, mentioned entities (email, date, time), recording URL, and
    dashboard URL.
  contact:
    name: Phonely
    url: https://www.phonely.ai
  license:
    name: Phonely Terms of Service
    url: https://www.phonely.ai/terms

defaultContentType: application/json

servers:
  customer-endpoint:
    host: example.com
    pathname: /phonely/webhook
    protocol: https
    description: |
      The customer-owned HTTPS endpoint that Phonely POSTs call data to. The
      endpoint must accept JSON, respond quickly to avoid sender timeouts, and
      log delivery failures. Configure the URL inside the agent workflow builder
      at /agent/{agentId}?tab=workflows.

channels:
  postCall:
    address: /phonely/webhook
    title: Post-Call Webhook
    description: |
      Delivered after a call has completed. The Send Call Data workflow action
      must be present in the agent's post-call workflow for this event to fire.
    messages:
      postCallEvent:
        $ref: '#/components/messages/PostCallEvent'

operations:
  receivePostCall:
    action: receive
    channel:
      $ref: '#/channels/postCall'
    title: Receive Post-Call Event
    summary: Phonely POSTs a post-call event payload to the configured webhook URL.
    bindings:
      http:
        method: POST

components:
  messages:
    PostCallEvent:
      name: PostCallEvent
      title: Post-Call Event
      summary: Structured call data delivered after a Phonely call completes.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PostCallEvent'

  schemas:
    PostCallEvent:
      type: object
      required:
        - callId
        - callDirection
        - callStarted
        - callEnded
        - duration
        - businessPhoneNumber
        - customerPhoneNumber
      properties:
        callId:
          type: string
          description: Unique identifier for the call.
        agentName:
          type: string
          description: Display name of the agent that handled the call.
        callerName:
          type: string
          description: Caller's name when known.
        callDirection:
          type: string
          description: Direction of the call.
          enum:
            - inbound
            - outbound
        callStarted:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the call started.
        callEnded:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the call ended.
        duration:
          type: number
          description: Call duration in seconds.
        businessPhoneNumber:
          type: string
          description: Business phone number assigned to the agent (E.164).
        customerPhoneNumber:
          type: string
          description: Caller's phone number (E.164).
        mentionedEmail:
          type: string
          nullable: true
          description: Email address mentioned during the call, if any.
        mentionedDate:
          type: string
          nullable: true
          description: Date mentioned during the call, if any.
        mentionedTime:
          type: string
          nullable: true
          description: Time mentioned during the call, if any.
        transcriptText:
          type: string
          description: Full text transcript of the call.
        transcript:
          type: array
          description: Structured transcript turns.
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                description: Speaker role for this turn.
                enum:
                  - agent
                  - user
              content:
                type: string
                description: Text content of the turn.
        summary:
          type: string
          description: Brief AI-generated summary of the call.
        longSummary:
          type: string
          nullable: true
          description: Detailed AI-generated summary of the call.
        purpose:
          type: string
          description: AI-extracted call objective.
        topic:
          type: string
          description: AI-extracted call topic / category.
        sentiment:
          type: string
          description: Overall sentiment of the call.
        keyPoints:
          type: array
          description: Highlighted insights from the call.
          items:
            type: string
        unansweredQuestions:
          type: array
          description: Caller questions that were not resolved.
          items:
            type: string
        actionItems:
          type: array
          description: Tasks generated by the call.
          items:
            type: string
        followUp:
          type: string
          description: Follow-up indicator.
        followUpReason:
          type: string
          description: Reason a follow-up is needed.
        ai_success:
          type: string
          description: AI performance / success metric for the call.
        recordingUrl:
          type: string
          format: uri
          description: HTTPS URL to the call recording.
        dashboardUrl:
          type: string
          format: uri
          description: HTTPS URL to view this call in the Phonely dashboard.
        endedReason:
          type: string
          description: Reason the call ended (e.g. caller_hangup, agent_hangup, transfer).