Create Campaign API
Pre-Requisites
To get started ensure you have the following checklist:
An access token issued by Ryng
A list of all agents & their IDs/usernames.
API Definitions and Parameters
URL
https://<subdomain>.ryng.in/rest-api/v1/campaign
Replace
<subdomain>with your account subdomain.
Method
POST
Headers
x-access-token
The access token is provisioned for you by Ryng. If you do not have this already, please reach out to your Ryng project champion. Alternatively, you can raise a request on our support portal.
Body
For this API, body parameters are accepted in either form-data or JSON format. You can choose the format that best suits your application's requirements or preferences. Note: In order to upload a csv sheet using the campaign-sheet param, you will need to use form-data, since this does not work over JSON
Type: form-data
campaign-sheet
file
Attach a .csv file with your lead/customer information that is to be assigned to your agents
Yes
agents
text
Specify one or more agents amongst whom the leads/customers should be assigned, or else, use “in-file” to provide agent mapping within the CSV file itself. If not specified, default value = all agents
Yes - if only one lead, or for in-file mapping. No - if more than one lead
campaign-name
text
Give a custom name for your campaign. This can be leveraged to indicate the source of lead or a unique identifier like lead# from your CRM. If not specified, Ryng will give random campaign name.
No
Type: JSON
name
String
Give a custom name for the campaign. This can be leveraged to indicate the source of lead or a unique identifier like lead# from your CRM. If not specified, the default value is “campaign::<campaignID>”
No
agentMapping
String
Specify how agents should be assigned to campaign calls • global - The agents to be assigned will be defined (by username) in the agents parameter • inline - Agents to be assigned for calls are fetched from the agentsAssigned parameter within jsonData, or from within the selected campaign • all-agents - (default) All agents are available to be assigned for campaign calls
agents
Array of Strings
Specify one or more agent usernames amongst whom the leads/customers should be assigned
Yes - if agentMapping set to implicit
customFieldNames
Object
Header names for custom fields. Object keys should be of the format customField{number}Name ex. { "customField1Name": "Name", "customField2Name": "Brand", "customField3Name": "Product" }
No
customerData
Object
Contains customer data to be uploaded to campaign. Check example body section for the example
→ connectCallbackUrl - Optional URL endpoint to trigger a callback at the major milestones of a call lifecycle. These milestones are: agent picks up, customer picks up, and call termination. Ryng will trigger one callback at each of these stages. The callback will contain all metadata for that particular call in the body, the format of which is given below. The API expects to receive a 200 OK response from the callback URL endpoint. On any non-200 response, Ryng will retry the callback after a 1 minute interval one more time.
→ terminalCallbackUrl - Optional URL endpoint to receive callbacks on the terminal state of each call (i.e., each row of customer data) in this request. One callback will be sent per call. The callback will contain all metadata and disposition details for that particular call, and will be sent as a POST request to this endpoint. Format of the callback is given below. The API expects to receive a 200 OK response from the callback URL endpoint upon successful receipt of the callback. On any non-200 response, Ryng will retry the callback at 1-minute intervals up to two more times. → jsonData - (json) Call data is specified as an array of call objects Default Fields → number - (Required) (String) Customer number to call for a given call → agentsAssigned - (Array of Strings) Comma separated list of assignable agents to a specific call → customField{Number} - (ex. customField1) (String) Custom field values for a given
Yes
Example Body
API Responses
Create Campaign API
POST https://tenant.ryng.xyz/rest-api/v1/campaign
Headers
x-access-token*
Provided by Ryng Team
Connect Callback Body Example
Terminal Callback Body Example
Case Study: Using Campaign API in transactional nature
The Campaign API is best suited for campaigns with more than one record, where you are sending records in bulk to Ryng. However, if you are trying to leverage this API in a transactional nature (that is a campaign with a single record) it is essential that you specify the agent for assignment.
If you are trying to leverage this API in a transactional nature, it is essential that you specify the agent for assignment.
For example, if you have the following agents:
And you have data flowing in as seen below:
10AM:
998314242
James
Life Insurance
XT243
10:15 AM:
893247489
Philip
Motor Insurance
XT250
If you were to post this to Ryng via the Campaign API without specifying agents, it would always assign both leads to Agent.id = 10 (i.e your first agent). This happens since the round-robin assignment is currently applicable only within a campaign, and not across.
To work around this, simply specify an agent id from your list of agents (provided by us), within your POST request.
In this scenario, your body for each request would look like:
10AM:
campaign-sheet
xt243.csv
agent
10
10:15 AM:
campaign-sheet
xt250.csv
agent
20
Last updated