Mango9 Documentation

Give a new enquiry a useful next conversation

VoiceAI API lets your integration request an outbound call from an AI agent configured in your Mango9 account. A lead form or another business tool can start the request as part of the follow-up journey.

The agent uses the business instructions, enabled tools and calling setup you prepared. For example, it can discuss a service enquiry, qualify interest and use its configured booking tools to arrange an appointment. SMS conversations and templates are configured in their corresponding messaging and workflow tools.

VoiceAI API endpoint cards for listing agents and placing a call — List the account’s outbound-capable agents first, then use the chosen assistant ID in a call request. Select the image to enlarge it.

Prepare the business calling setup

Connect Telnyx as your carrier and obtain the phone numbers the campaign will use.
Create the AI agent, add the business information and configure its available booking or other tools. Enable its outbound calling mode.
Review its caller ID, calling window and the account’s available balance.
Use GET /app/api/voiceai/agents with the saved key to list eligible agents on the same Mango9 server.
Keep the returned assistant_id for the agent that should handle this campaign.

Describe the call request

Describe the call request
Field	Use
key	The account’s saved API secret.
assistant_id	The assistant ID from the agent list.
phone	The recipient number in international form, such as +12025550147 for a reserved example.
first_name, last_name, contact_email, contact_name	Optional contact context for the conversation.
caller_id	Optional override using an active number belonging to the account.
dynamic_variables	Optional JSON object with the values the configured agent expects.

Use the test form deliberately

VoiceAI API test form with assistant selection, phone and first name — Illustrative test fields. Refresh Agents needs a valid saved key to load the account’s choices; no call was placed during this review. Select the image to enlarge it.

Open VoiceAI API and paste the saved secret into API Key.
Select Refresh Agents and choose the intended assistant.
Enter a number you control and any first-name context for the test.
Select Place Call when you are ready to receive an actual outbound call.
Review the returned call IDs and the call activity, then confirm the conversation and any intended appointment result.

Read the outcome before retrying

Read the outcome before retrying
Response	Meaning	Next step
err 00 / initiated	The call was initiated.	Store the call IDs and follow the activity; initiation does not mean the customer answered.
err 07 / deferred	No call was placed because of the calling window or call-rate limit.	Read wait_until, timezone and reason; arrange a later attempt in your integration.
err 05	Insufficient account balance.	Review the account balance before another attempt.
err 01 / 02	Missing or invalid API key.	Check the saved secret and the account server.
Other error	Required data, agent access or call setup needs attention.	Read msg and data.reason and correct the request or setup.

Use the same follow-up rules across channels

The API uses the same outbound calling service as Mango9 workflow AI calls. The account’s calling setup, agent window and applicable call controls continue to apply.

For a consultation campaign, connect the enquiry to the right contact, have the configured AI agent discuss the request, then use the booking record and SMS template to confirm the next step. Keep the call IDs, contact ID and appointment record together so the team can follow the customer’s progress.

VoiceAI API