> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d-api.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger an agent call (public trigger URL)

> Public by design: the token in the URL is the credential (no API key). Create the trigger in the dashboard.

JSON body (up to 16 KB): `phone` (with country code; a BR number without country code gets 55), optional `sessionId` (trigger default), optional `variables` (only variables declared on the agent; up to 30, values up to 500 characters). Flat top-level keys `"variables.<name>": value` are also accepted (the `variables` object wins on conflict).

Signature (when the trigger requires it): `X-DAPI-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + body)>`, 300 s tolerance.

`Idempotency-Key` (up to 128): repeats within 24 h get the same response. Without it, the same phone + variables within 60 s also do.

Outside the trigger's time window the call is scheduled for the next opening (`status: "scheduled"`).

Errors: 404 `not_found`, 423 `trigger_paused`, 401 `invalid_signature`, 400 `invalid_input`/`missing_variables`, 403 `session_not_allowed`/`country_not_allowed`, 409 `agent_not_published`/`request_in_progress`, 402 `insufficient_balance`/`daily_cap_reached`, 413 `payload_too_large`, 429 `rate_limited` (with `retryAfterSec` and Retry-After)/`queue_full`.



## OpenAPI

````yaml /api-reference/openapi.en.json post /api/v1/hooks/va/{token}
openapi: 3.1.0
info:
  title: D-API - Complete WhatsApp Infrastructure
  description: >-
    A scalable, robust solution for automation managers, SaaS products and end
    users who need a reliable WhatsApp integration. It offers multiple
    simultaneous instances, real-time webhooks, an intuitive dashboard and a
    documented REST API with 99.9% uptime and latency under 30ms.
  version: 1.2.1
  contact:
    name: Suporte D-API
    email: suporte@d-api.cloud
    url: https://d-api.cloud
servers:
  - url: https://api.d-api.cloud
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Home
    description: Base endpoints
  - name: Sessions
    description: Endpoints for managing sessions
  - name: Messages
    description: Endpoints for sending messages
  - name: Cloud API
    description: >-
      WhatsApp Official API (Meta Cloud API): manual connection, template
      management (list/create/delete) and template sending.
  - name: IVR Calls
    description: 'Voice call dispatch (IVR): single or bulk, with audio or an IVR flow.'
  - name: SMS
    description: 'SMS sending: single or bulk.'
  - name: Commands
    description: >-
      Look up asynchronous commands (async: true) by the commandId returned when
      enqueued.
paths:
  /api/v1/hooks/va/{token}:
    post:
      tags:
        - Voice agents — triggers
      summary: Trigger an agent call (public trigger URL)
      description: >-
        Public by design: the token in the URL is the credential (no API key).
        Create the trigger in the dashboard.


        JSON body (up to 16 KB): `phone` (with country code; a BR number without
        country code gets 55), optional `sessionId` (trigger default), optional
        `variables` (only variables declared on the agent; up to 30, values up
        to 500 characters). Flat top-level keys `"variables.<name>": value` are
        also accepted (the `variables` object wins on conflict).


        Signature (when the trigger requires it): `X-DAPI-Signature:
        t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + body)>`, 300 s tolerance.


        `Idempotency-Key` (up to 128): repeats within 24 h get the same
        response. Without it, the same phone + variables within 60 s also do.


        Outside the trigger's time window the call is scheduled for the next
        opening (`status: "scheduled"`).


        Errors: 404 `not_found`, 423 `trigger_paused`, 401 `invalid_signature`,
        400 `invalid_input`/`missing_variables`, 403
        `session_not_allowed`/`country_not_allowed`, 409
        `agent_not_published`/`request_in_progress`, 402
        `insufficient_balance`/`daily_cap_reached`, 413 `payload_too_large`, 429
        `rate_limited` (with `retryAfterSec` and Retry-After)/`queue_full`.
      operationId: postApiV1HooksVaByToken
      parameters:
        - schema:
            type: string
          in: path
          name: token
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone
              properties:
                phone:
                  oneOf:
                    - type: string
                    - type: number
                  example: '5511999990000'
                sessionId:
                  type: string
                variables:
                  type: object
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: number
                      - type: boolean
      responses:
        '202':
          description: Call queued or scheduled
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                      callId:
                        type: string
                      status:
                        type: string
                        enum:
                          - queued
                      queuePosition:
                        type:
                          - integer
                          - 'null'
                  - type: object
                    properties:
                      success:
                        type: boolean
                      status:
                        type: string
                        enum:
                          - scheduled
                      scheduledFor:
                        type: string
                        format: date-time
                      requestId:
                        type: string
        '400':
          description: invalid_input / missing_variables
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '401':
          description: invalid_signature
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '402':
          description: insufficient_balance / daily_cap_reached
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '403':
          description: session_not_allowed / country_not_allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '404':
          description: Trigger not found or revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '409':
          description: agent_not_published / request_in_progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '413':
          description: payload_too_large
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '423':
          description: trigger_paused
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
        '429':
          description: rate_limited / queue_full
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  code:
                    type: string
                  message:
                    type: string
      security: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key for authentication. Format: <API_KEY>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.