/contacts/
Get a list of all contacts. Each contact has the following keys
url
String
URL of the contact
phonebooks
Array
URL of all the phone books that the contact belongs to
contact
String
Phone number of the contact. This is used is all voice campaigns
mobile
String
Mobile phone number of the contact. This is used in all text message campaigns
last_name
String
Last Name of the contact
first_name
String
First Name of the contact
country_code
String
2 letter country code. This is used to add the country prefix to the phone numbers, if necessary. See the full list of 2 letter country codes here http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
String
Email Address
address
String
Address of the contact
city
String
City
state
String
State
company_name
String
Name of the company/organisation the contact belongs to
company_website
String
Website of the contact's organisation
job_title
String
Job Title/Function
/contacts/fields/
Get a list of all contact fields. Each contact field details has the following keys
id
Integer
Contact Field ID.
name
String
Contact Field Name.
/contacts/bulk_create/
Few important details on API /contacts/bulk_create/
- Bulk create API has rate limit of 1 call per minute. So you can't call this API at high rates.
- If your API request is throttled, we return the details of when the API is free to accept the next request.
- All submitted imports will get processed one at a time. So even if you submit 5 CSV files by making the API call 5 times, the import will finish the first CSV file, then go for the second one, so on and so forth.
- Tags column in CSV should be in format of comma separated tags.
/phonebooks/
List all the phone books. Each phone book will have the following keys
url
String
URL to the phone book
owner
String
User name of your CallHub account
name
String
Name of the phone book
description
String
Description of the phone book
/phonebooks/:id/contacts/
List all contacts in the phone book. Each contact will have all contact details.
/custom_fields/
Get a list of all custom fields by passing no Path Params. Pass the Path Param for getting particular
custom fields. Each custom field has the following keys
id
Auto
Custom Field ID.
owner
String
User that is logged in.
name
String
Name of custom field.
field_type
String
Field type of the custom field.
cfmultichoice
List
If field_type is Multi-choice, It is the list of choices.
created_date
datetime
Creation date of the custom field.
updated_date
datetime
Date at which custom field is modified.
/webhooks/
Create new web hook. See below for possible values for event and when they are fired
vb.transfer
Occurs when the transfer digit is pressed in a voice broadcast campaign
sb.reply
Occurs when a text reply is received in your CallHub account
cc.notes
Occurs when a note is added by a call center agent
agent.activation
Occurs when agent activates their account by clicking on the activation link
The following keys will be received as data when the vb.transfer event occurs.
audio_url
String
URL to the Audio Message received, if it exists
transcript_content
String
Transcript of the Audio Message received, if transcript is enabled
from_number
String
Phone number from which the transfer digit was pressed
transcript_url
String
URL to the transcript of the Audio Message received, if transcript is enabled
campaign
String
Name of the Voice Broadcast Campaign that generated this event
The following keys will be received as data when the sb.reply event occurs.
content
String
Content of the message received
from_name
String
Name of the person sending the text message
from_number
String
Phone number of the person sending the text message
campaign
String
Name of the text campaign that this reply is received for
The following keys will be received as data when the cc.notes event occurs.
city
String
City of the person
first_name
String
Person's first name
last_name
String
Person's last name
campaign
String
Call center campaign name
mobile
String
Mobile number of the Person
country
String
Person's country
notes
String
Notes saved by the agent
zipcode
String
Person's zipcode
record_url
String
Recording of the conversation between agent and person
company_website
String
Website of person's company
state
String
State to which person belongs
contact
String
Contact Number of the person
nationbuilder_tags
String
Nation Builder Tags associated with the person
nationbuilder_id
Integer
Nation Builder Id of the contact
company_name
String
Name of the company where person works
String
Email address of the contact
address
String
Address where person stays
job_title
String
Person's job title
disposition
String
Disposition selected for this call
surveys
Array
Key value pairs of survey questions and responses
agent.id
Integer
Id of the agent who saved notes
agent.username
String
username of the agent who saved notes
agent.email
String
email address of the agent for whom the notes were added
agent.nationbuilder_id
Integer
Nation Builder Id of the agent
The following keys will be received as data when the agent.activation event occurs.
id
Integer
Id of the agent that got activated
username
String
username of the activated agent
String
Email address of the agent
activated_at
String
Date time in UTC when agent got activated
Example Event Hook Responses
{
"hook": {},
"data": {
"audio_url": "https://s3.amazonaws.com/recordings/1c112f10-d15a-1964-b894-842bFE5655.mp3",
"transcript_content": "Hey, Thanks for the call. See you on Friday",
"from_number": "15104024173",
"transcript_url": "https://s3.amazonaws.com/recordings/1c112f10-d15a-1964-b894-842bFE5655.txt",
"campaign": "Voice Broadcast, Apr 03, 06:42"
}
}
{
"hook": {},
"data": {
"content": "Yes, I will be there!",
"from_name": "John Doe",
"from_number": "16502293681",
"campaign": "Friday Party Invite"
}
}
{
"city": "Santa Clara",
"first_name": "John",
"last_name": "Doe",
"campaign": "Fishy Campaign",
"mobile": "16507868629",
"country": "HU",
"notes": "This person loves fish!",
"zipcode": "50103",
"record_url": "https://s3.amazonaws.com/recordings/081eecf6-dsfdsgdfg4e051700.mp3",
"company_website": "https://callhub.io/",
"state": "CA",
"contact": "16507868628",
"nationbuilder_tags": [
"survey responded",
"fish owner"
],
"company_name": "CallHub",
"address": "Genesis Suncity",
"job_title": "Engineer",
"disposition": "MEANINGFUL_INTERACTION",
"surveys": [
{"answer": "A", "type": "MultiChoice", "question": "You like A or B?"},
{"answer": "My Text", "type": "Text", "question": "What is your text?"},
{"answer": 32, "type": "Numeric", "question": "Your age?"}
],
}
/webhooks/
List of Webhooks that are registered
id
Integer
ID of the webhook
url
String
URL to the webhook
user
String
URL of the user details endpoint
created
String
Date of creation of the webhook
updated
String
Last change time
event
String
CallHub Event on which the webhook will get fired
target
String
URL that will be called when the event is fired in CallHub
/callcenter_campaigns/
List of all your Call Center Campaigns. Each campaign has the following keys
url
String
URL of the call center campaign
owner
String
CallHub User Name
name
String
Name of the campaign
status
Integer
Status of the campaign. It corresponds to the following status:
1 - START
2 - PAUSE
3- ABORT
4- END
phonebook
Array
Array of URLs of the phone books associated with this campaign
/voice_broadcasts/
List of all your voice broadcast campaigns. Each campaign has the following keys:
url
String
URL of the voice broadcasting campaign
owner
String
CallHub User Name
name
String
Name of the campaign
frequency
Integer
Number of calls per minute
status
Integer
Status of the campaign. It corresponds to the following status:
1 - START
2 - PAUSE
3- ABORT
4- END
phonebook
Array
Array of phone books associated with this campaign
/sms_campaigns/
List of all your SMS campaigns. Each campaign has the following keys
url
String
URL of the SMS campaign
owner
String
CallHub User Name
name
String
Name of the campaign
status
Integer
Status of the campaign. It corresponds to the following status.
1 - START
2 - PAUSE
3- ABORT
4- END
phonebook
Array
Array of phone books associated with this campaign
/users/
Calling /users will return your user information along with its related objects
Each user will have the following keys
url
String
The user URL
username
String
CallHub user name
String
Email address of the CallHub account
bphones
Array
Array of urls to the business phones in the account
phonebooks
Array
Array of urls to the phonebooks in the account
voice_broadcasts
Array
Array of voice campaigns in the account
sms_campaigns
Array
Array of SMS campaigns in the account
callcenter_campaigns
Array
Array of Call Center campaigns in the account
/dnc_contacts/
Get a list of all DNC contacts. Each contact has the following keys
url
String
URL of the dnc contact
dnc
String
URL of the DNC list that the contact belongs to
phone_number
String
Phone number of the contact.
/dnc_lists/
List all the phone books. Each phone book will have the following keys
url
String
URL to the DNC list
owner
String
User name of your CallHub account
name
String
Name of the DNC list
/agents/:id/
List agent with agent Id
id
Integer
Agent Id
username
String
Agent username
String
Agent email address
owner
String
Agent's owner
/agents/
Api to create an agent. On POST, an agent gets created but no owner is assigned. Agents will receive an email for verification. Once they verify their account, owner gets assigned and then they are free to make calls
/campaign/agent/live/
Api to get list of Connected Agents to any campaign, it uses Manager API key.
/teams/:id/agents/
Adds a list of existing agents to the team
API to assign existing agents to a team
/agent-status/
Get the current agent status
Fetch the current status of the agent here.
This API returns 5 properties. Each property signifies a different stage in the lifecycle of an agent connecting to a campaign and making calls.
If all of the properties are null, then the agent has not joined any campaign and is not on call.
Once the /conference api is used successfully to connect to a campaign, the connected_campaign
field returns the ID of the connected campaign.
When the /conference/:id/agent api is used successfully to call the agent and the agent picks the call, the call_uuid
returns the ID of the call.
After using /conference/:id/subscriber successfully to initiate a call with the subscriber, the current_subscriber
field returns the ID of the subscriber being called.
After the subscriber picks up the call, subscriber_uuid
returns the UUID of the call.
After using /conference/:id/supervisor to call the supervisor and the supervisor picks up the call, the supervisor_uuid
returns the UUID of the supervisor's call.
/user-details/
Get the details of the agent
This API returns details of the agent.
user.first_name
First name of the Agent
user.last_name
Last name of the Agent
user.email
Email of the agent
agent.country
Selected Country of the Agent
agent.phone_no
Phone Number of the agent. This phone number will be called when agent joins a campaign
agent.language
Language of the agent. Change this to change the language of the messages returned on success or failures of APIs
/user-details/
Save details of the agent
This API can be used to save the details of the agent.
/password-change/
Change the Password of the Agent
Use this API to change the password of the agent
/sip-endpoint/
Get the SIP endpoint details of the agent
Use the SIP endpoint details in a SIP client to receive calls on the client.
/nation-builder/
Get the Agent's NationBuilder details
If the agent has connected their NationBuilder account to the CallHub account, then this API returns the slug of the nation that they have connected to.
/is-trophy/
Get details of whether the agent is the best agent in that campaign and if not, who is
Check whether the agent is the best agent for that campaign and if not, get the details of the best agent.
/agent-campaigns/
Get the IDs of all the campaigns the agent has been assigned to.
This API will return all the IDs of the campaigns that the agent has been assigned to.
/campaign-info/
Details on the campaigns
This API can be used to fetch the informations of the campaigns the agent has been assigned to. Use the /agent-campaigns API to fetch all the assigned campaigns.
This returns an array of Campaign-Info objects, each containing information about the campaign.
status
assign_agents
code
name
script
invite_person
incoming_id
totalcontact
team
completed
voicemail_audiofile
recording
phonebook
pending_notes
created_date
notes_required
voicemail_detection
id
/script-sections/:id/
Get the script sections assigned to a campaign
The API provides the script and survey questions of the campaign. Using the response of this API the script/survey page of the call center can be designed.
/script-answers/:id/
Post answers to survey questions
Post answers to the script and survey questions
/subscriber-history/:id/
Get the history for a subscriber
Lists all the available voice,sms and call center history about the current contact being called in the call center campaign.
/conference
Create a conference object
Create a new conference object for agent to join the campaign.
Use the conference_uuid
property in the returned object for all subsequent conference calls such as /conference/:id/agent, /conference/:id/subscriber etc.
/conference/:id
Get a conference object
Get the conference object created by the agent using a conference_uuid.
/conference/:id/agent
Join agent to the conference
Agent joins the conference through API to start making calls for the campaign.
/conference/:id/subscriber
Make call to next subscriber
The API is used to call the next available subscriber in the contact list of the call center campaign.
/conference/:id/subscriber/voicemail
Drop voicemail to subscriber
Drop voicemail to the subscriber. Calling this API hangs up the call and leaves a message selected by the campaign manager when creating a campaign.
/conference/:id/supervisor
Call a phone number to a third party who will join the call with the subscriber
/conference/:id/subscriber/transfer
Hand over a call with the subscriber to the supervisor
After the supervisor joins the call, the agent can hand over the call to the supervisor and leave the call. This allows the agent to move onto the next call with the call between the Supervisor and the Subscriber still ongoing.
/conference/:id/supervisor
Hangup supervisor from the conference
The supervisor will be removed from the conference and the agent will once again be only connected to the subscriber
/dialer/
Create a dialer object
Create a new dialer object for agent to call the contact.
Use the dialer_uuid
property in the returned object for all subsequent dialer calls such as /dialer/:id/agent etc.
/dialer/:id/
Get a dialer object
Get the dialer object created by the agent using a dialer_uuid.
/dialer/:id/agent/
Dialing call to the contact
Agent get a call and the it will connect contact to the agent.
num_type - you can call contact on mobile or landline.
For mobile give num_type - 'mobile' and for landline give num_type - 'contact'
/contact-notes/:id/
Saving notes for contact
Notes for the conversation will be saved. And you can see notes here dialer call reports
/collective_texting/campaigns/{campaign_id}/saved_replies/
Get list of saved replies added by manager in the campaign
/collective_texting/campaigns/{campaign_id}/subscribers/
Get list of all subscribers for the agent
/collective_texting/subscribers/{subscriber_id}/messages/
Get all messages of a subscriber