VayaFlow
Voice Calls

Initiate an AI voice call

Triggers an outbound AI voice call to a contact. The call is placed asynchronously and the response returns immediately with an interaction ID for tracking. Pre-flight validation checks that the contact exists with a valid E.164 phone number, the playbook is active with a voice agent configured, the contact is not on the Do Not Call list, and auto-dialer rules are satisfied (operating hours, min gap, max attempts). Use webhooks to receive call completion events, or poll the interaction for status updates.

POST
/api/v1/voice/calls/initiate

Authorization

ApiKeyAuth
X-API-Key<token>

API key generated from your Vayaflow dashboard Settings page

In: header

Request Body

application/json

contactId*string

The contact to call

direction?string

Call direction. Defaults to outbound.

Default"outbound"
Value in"inbound" | "outbound"
phone?string

Override the contact's phone number (E.164 format). If omitted, uses the contact's phone on file.

playbookId?string

The playbook this call is for. The contact must be active in it. If omitted, uses the contact's current playbook; a contact in no playbook is refused (NOT_IN_PLAYBOOK).

additionalInstructions?string

Extra instructions appended to the voice agent's prompt for this call.

isTest?booleanDeprecated

Deprecated and ignored. Whether a call is a test comes from the contact (test contacts).

Response Body

application/json

application/json

application/json

application/json

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.vayaflow.com/api/v1/voice/calls/initiate"  body := strings.NewReader(`{    "contactId": "contact_abc123"  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}
{
  "success": true,
  "data": {
    "interactionId": "int_abc123",
    "contactId": "string",
    "playbookId": "string",
    "agentId": "string"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      "string"
    ]
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Get a playbook

Returns a single playbook by its playbook ID.

Send an SMS message

Sends an SMS message to a contact. Only the contact ID and message are required — the recipient phone, sender phone, and SMS provider are automatically resolved from the contact and playbook configuration. The recipient defaults to the contact phone on file. The sender is resolved from the playbook assigned phone number, then the SMS agent phone, then the first SMS-capable number. The provider follows the playbook-level override, then the tenant default, then Vonage. If an interactionId is provided, the message is appended to an existing conversation. Otherwise, the system finds or creates a conversation automatically.