Make an outbound phone call

Make an outbound phone call with one of your AI phone agents.

POST https://app.ringly.io/api/1.1/wf/make-outbound-call

---

Headers

You can find your Ringly.io API key in Settings > API key and then generate an API key.

Name	Value
Content-Type	application/json
Authorization	<Your Ringly.io API key>

Body

---

from_number string required

A phone number you own in Ringly.io, in E.164 format. Example: "[phone]".

---

to_number string required

The number you want to call, in E.164 format. Example: "[phone]".

---

agent_tag string required

The tag of one your AI phone agents. Does not need to have a phone number, as long as the 'from_number' is yours. Example: "agent_124532h23i5ad2543b3289bsj3". You can find the agent_tag by going to your agent, and scroll all the way down. Note: not all agent_tag's start with "agent_"

---

customer_name string optional

The name of the customer you're calling. This way, you can use it in your agent's instructions and greeting. For example, use this as your greeting: Hey this is Jack, am I speaking with {{customer_name}}? Ringly.io will automatically replace {{customer_name}} with the actual customer name.

---

Example requests

cURL

curl --request POST \
  --url https://app.ringly.io/api/1.1/wf/make-outbound-call \
  --header 'Authorization: Your_Ringly_API_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "from_number": "[phone]",
  "to_number": "[phone]",
  "agent_tag": "agent_1234abcd",
  "customer_name": "John"
}'

Python

import requests

url = "https://app.ringly.io/api/1.1/wf/make-outbound-call"

payload = {
    "from_number": "[phone]",
    "to_number": "[phone]",
    "agent_tag": "agent_1234abcd",
    "customer_name": "John"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Your_Ringly_API_key"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Ruby

require 'uri'
require 'net/http'

url = URI("https://app.ringly.io/api/1.1/wf/make-outbound-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Your_Ringly_API_key'
request.body = "{\n  \"from_number\": \"[phone]\",\n  \"to_number\": \"[phone]\",\n  \"agent_tag\": \"agent_1234abcd\",\n  \"customer_name\": \"John\"\n}"

response = http.request(request)
puts response.read_body

JavaScript

fetch('https://app.ringly.io/api/1.1/wf/make-outbound-call', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Your_Ringly_API_key'
  },
  body: JSON.stringify({
    from_number: '[phone]',
    to_number: '[phone]',
    agent_tag: 'agent_1234abcd',
    customer_name: 'John'
  })
})

Response

201

{
  "from_number": "[phone]",
  "to_number": "[phone]",
  "agent_tag": "agent_b7893d54b31985d73b459",
  "call_status": "registered",
  "customer_name": "John"
}

400

{
  "error_message": "Invalid request format, please check API reference."
}

401

{ 
  "error_message": "API key is missing or invalid." 
}

402

{ 
  "error_message": "Trial has ended, please add payment method." 
}

422

{ 
  "error_message": "Cannot find requested asset under given api key." 
}

429

{ 
  "error_message": "Account rate limited, please throttle your requests." 
}

500

{ 
  "error_message": "An unexpected server error occurred."
}

Make sure you adhere to local laws and regulations when making outbound phone calls. Read our Terms of Service for more.