curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "contact",
"contactId": "456e4567-e89b-12d3-a456-426614174000"
}'
curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "phoneNumber",
"phoneNumber": "+14155551234",
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"businessName": "Acme Inc",
"customFields": {
"Lead Source": "Website",
"Company Size": "50-100"
}
}'
{
"conversationId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"type": "https://api.nedzo.ai/errors/outbound-trial-gate",
"title": "Payment Required",
"status": 402,
"detail": "Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts."
}
Conversations
Start a call
Place an outbound AI voice call with an agent, to a contact or a phone number.
POST
/
conversations
/
call
curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "contact",
"contactId": "456e4567-e89b-12d3-a456-426614174000"
}'
curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "phoneNumber",
"phoneNumber": "+14155551234",
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"businessName": "Acme Inc",
"customFields": {
"Lead Source": "Website",
"Company Size": "50-100"
}
}'
{
"conversationId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"type": "https://api.nedzo.ai/errors/outbound-trial-gate",
"title": "Payment Required",
"status": 402,
"detail": "Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts."
}
Place an outbound call with an agent. The response gives the
conversationId at once, and the call is placed in the background. Read the result with Get a conversation once the call ends.
Every plan with calls can use this endpoint. It takes the same body as Make a call (POST /v1/call), which it replaces.
Every call checks Do Not Disturb (DND) first. If the contact has DND on, or the number is on the opt-out list, the call is refused with
403 and no call is placed.string
required
UUID of the agent to use for the call
string
required
Type of call target. Valid values:
contact, phoneNumberobject
Custom variables to pass to the assistant. These override contact field values.
- Contact
- Phone Number
The agent must have a phone number assigned in Agent Builder > Settings before you can make outbound calls. Calls fail with
400 Bad Request if the agent has no number connected. Nedzo never uses another number in the workspace, because the person would see the wrong caller ID.Every call ends at the agent’s Max call duration (set on the agent’s Settings tab, 1 to 60 minutes, 30 by default). The cap covers the whole call, including any time after a transfer to a person. See How Max call duration works.
Outbound calls go live when your trial converts to a paid plan. Until then, this endpoint refuses the call with
402 and type outbound-trial-gate, and no call is placed. The one exception is a number verified in your workspace, such as your own phone, which you can call during the trial.Errors
| Status | Detail | Cause |
|---|---|---|
400 | Agent does not have a phone number assigned. Please assign a number in Agent Builder > Settings before making outbound calls. | The agent has no phone number connected. |
400 | Phone number <number> is not active. Please activate it first. | The agent’s assigned number is in pending or another non-active status. |
400 | Invalid call type | type is something other than contact or phoneNumber. |
400 | The agent's number cannot place outbound calls. Assign a US or Canada number from Nedzo, or a verified caller ID. | The agent’s number can’t make outbound calls. |
402 | Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts. | The account is on a trial. The type ends in outbound-trial-gate. |
402 | Varies | The account has no plan, its subscription is not active, or its wallet has no balance left. The type ends in payment-required. |
403 | Contact has Do Not Disturb (DND) on | A contact with this number has DND on, the contact found by this email has DND on, or the number is on the opt-out list. No call was placed. |
403 | Contact processing is restricted (GDPR Art.18) | The contact’s data is restricted. No call was placed. |
403 | Could not verify Do Not Disturb status | Nedzo couldn’t check the opt-out list, so it placed no call. Try again. |
403 | Your plan does not include calls. | Your plan does not include calls. |
404 | Agent not found | The agent is not in the workspace, or it was deleted. |
404 | Contact not found | The contact is not in the workspace. |
429 | Varies | The plan’s concurrent call limit is reached, or the account is over its write rate. No call was placed. Read Retry-After. |
500 | Could not look up the contact for this number. Please try again. | Nedzo couldn’t read the contacts on this number, so it placed no call. Try again. |
500 | Could not look up the contact for this email. Please try again. | Nedzo couldn’t read the contact with this email, so it placed no call. Try again. |
500 | Could not check this number against the Do Not Disturb list. Please try again. | Nedzo couldn’t check DND, so it placed no call. Try again. |
500 | Could not check this contact against the Do Not Disturb list. Please try again. | Nedzo couldn’t check DND, so it placed no call. Try again. |
503 | Could not check the concurrent call limit. Please retry shortly. | Nedzo couldn’t count the calls in progress. No call was placed. Read Retry-After. |
503 | We couldn't check this workspace's limits just now. Try again in a moment. | Nedzo couldn’t check the workspace’s limits. No call was placed. |
curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "contact",
"contactId": "456e4567-e89b-12d3-a456-426614174000"
}'
curl -X POST https://api.nedzo.ai/v1/conversations/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"type": "phoneNumber",
"phoneNumber": "+14155551234",
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"businessName": "Acme Inc",
"customFields": {
"Lead Source": "Website",
"Company Size": "50-100"
}
}'
{
"conversationId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"type": "https://api.nedzo.ai/errors/outbound-trial-gate",
"title": "Payment Required",
"status": 402,
"detail": "Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts."
}
Was this page helpful?