Skip to main content

Say

Overview​

The say action plays text-to-speech audio into the call. Use it for greetings, instructions, confirmations, and short prompts before another action. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put say before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use say for a receptionist-style greeting before an IVR menu or transfer. A common business flow is a front desk line that says the company name, gives the caller confidence they reached the right place, then continues into gather or transfer.

JSON Example​

{
  "actions": [
    {
      "say": {
        "text": "Thank you for calling Acme Clinic. Press 1 for appointments or 2 for billing."
      }
    }
  ]
}

Parameters​

FieldTypeRequiredDescription
textstringYesText to speak to the caller. Keep it concise so the caller hears the prompt quickly.

Execution Flow​

  1. MiniVoice reads the next action from your answer_url response.
  2. It validates that text is present and is a string.
  3. MiniVoice converts the text to playable audio and plays it into the active call.
  4. When playback finishes, MiniVoice continues with the next action in the actions array.

Webhook Behaviour​

The say action does not send an action-specific webhook. You still receive normal call lifecycle webhooks, such as call.answered and call.completed.

Success Example​

A successful answer_url response includes the action in a valid actions array:

{
  "actions": [
    {
      "say": {
        "text": "Thank you for calling Acme Clinic. Press 1 for appointments or 2 for billing."
      }
    }
  ]
}

Your application should store the MiniVoice call ID from webhooks or API responses so you can correlate the action with the call.

Failure Behaviour​

If text is empty or cannot be played, the action fails and later actions may not run. Keep prompts short and test phrasing with real calls before relying on them in an IVR.

Expected Result​

The caller hears the spoken greeting, then MiniVoice continues to the next action in the same actions array. No action-specific webhook is sent for the spoken prompt; use normal call lifecycle webhooks to track the call.

Testing​

Call a DID assigned to your application and return a single say action. Confirm the caller hears the spoken text, then add a second action such as gather or transfer. During testing, log every webhook payload and compare the call ID, action timing, and final call status with the behavior you expected.

Integration guidance

Place this action in a short answer_url response first, then combine it with other actions after you have confirmed the single-action behaviour. Always log the answer_url response your application returned for the call. If the caller experience differs from what you expected, compare the logged response with the webhook timeline for that call ID.

When this action is part of a larger IVR, keep each step explicit. For example, play a prompt before collecting input, redirect after collecting input, and transfer only after your application has selected the final destination. This makes the flow easier to test and easier to change later.

For production integrations, build a fallback path. A caller may hang up, enter no digits, reach a busy destination, or disconnect before the flow completes. Your webhook handler should update the call record with the last known step so support teams can understand what happened.

Copy/Paste Examples​

Real Request​

Return this from your answer_url:

{
  "actions": [
    {
      "say": {
        "text": "Thank you for calling Acme Clinic. Press 1 for appointments or 2 for billing."
      }
    }
  ]
}

Real Response​

A valid answer_url response is the JSON action payload itself. MiniVoice accepts the response when it contains an actions array:

{
  "actions": [
    {
      "say": {
        "text": "Thank you for calling Acme Clinic. Press 1 for appointments or 2 for billing."
      }
    }
  ]
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Use say for a receptionist-style greeting before an IVR menu or transfer. A common business flow is a front desk line that says the company name, gives the caller confidence they reached the right place, then continues into gather or transfer.

Common Failure Case​

{
  "error": {
    "code": "answer_url_error",
    "message": "invalid action payload"
  }
}

Invalid fields or malformed JSON cause MiniVoice to reject the answer_url payload. Log the exact response your server returned while testing.