ViciDial/agc_2-X
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bdeb0634b25a1bbe454cf9b7a14c3053f409bc75
agc_2-X/docs/AGENT_API.txt
T
mattf f7e85bd029 Added CRM Login Popup to campaign settings to allow for a custom window to be opened on agent login, optionally using agent and campaign variables 
Added 5 custom fields to the user settings
Added st* functions to agent api

git-svn-id: svn://192.168.202.10@1276 3d104415-ff17-0410-8863-d5cf3c621b8a
2009-12-13 01:03:54 +00:00

302 lines
12 KiB
Plaintext
Raw Blame History

AGENT API DOCUMENT Started: 2008-07-03
This document describes the functions of an API(Application Programming Interface)
for the VICIDIAL Agent screen. This functionality will be rather limited at first
and will be built upon as critical functions are identified and programmed into it.
There is also a new NON-agent API script, for more information on that, please
read the NON-AGENT_API.txt document.
API functions:
version - shows version and build of the API, along with the date/time
external_hangup - sends command to hangup the current phone call for one specific agent(Hangup Customer)
external_status - sends command to set the disposition for one specific agent and move on to next call
external_pause - sends command to pause/resume an agent now if not on a call, or pause after their next call if on call
external_dial - sends command to manually dial a number on the agent's screen
change_ingroups - changes the selected in-groups for a logged-in agent
st_login_log - looks up the vicidial_users.custom_three field and logs event from CRM
st_get_agent_active_lead - looks up active lead info for an agent and outputs lead information
New scripts:
/agc/api.php - the script that is accessed to execute commands
Required variables for API calls:
# user - is the API user
# pass - is the API user password
# agent_user - is the vicidial agent user whose session that you want to affect
# source - description of what originated the API call (maximum 20 characters)
To hangup the call, disposition it and then pause the agent, do the following in order:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_pause&value=PAUSE
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_hangup&value=1
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_status&value=A
Response to calls will return either an ERROR or a SUCCESS along with an explanation.
for example:
SUCCESS: external_status function set - 6666|A
ERROR: agent_user is not logged in - 6666
DETAIL OF EACH FUNCTION:
--------------------------------------------------------------------------------
version -
DESCRIPTION:
shows version and build of the API, along with the date/time
VALUES: NONE
EXAMPLE URL:
http://server/agc/api.php?function=version
RESPONSES:
VERSION: 2.0.5-2|BUILD: 90116-1229|DATE: 2009-01-15 14:59:33|EPOCH: 1222020803
--------------------------------------------------------------------------------
external_hangup -
DESCRIPTION:
Hangs up the current customer call on the agent screen
VALUES: (value)
1 - the only valid value for this function
EXAMPLE URL:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_hangup&value=1
RESPONSES:
ERROR: external_hangup not valid - 1|6666
ERROR: no user found - 6666
ERROR: agent_user is not logged in - 6666
SUCCESS: external_hangup function set - 1|6666
--------------------------------------------------------------------------------
external_status -
DESCRIPTION:
Sets the status of the current customer call on the agent dispotion screen
VALUES: (value)
Any valid status in the VICIDIAL system will work for this function
EXAMPLE URL:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_status&value=A
RESPONSES:
ERROR: external_status not valid - A|6666
ERROR: no user found - 6666
ERROR: agent_user is not logged in - 6666
SUCCESS: external_status function set - A|6666
--------------------------------------------------------------------------------
external_pause -
DESCRIPTION:
Pauses or Resumes the agent. If a Pause and the agent is on a live call will pause after the live call is dispositioned
VALUES: (value)
PAUSE - Pauses the agent session
RESUME - Resumes the agent session
EXAMPLE URLS:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_pause&value=PAUSE
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_pause&value=RESUME
RESPONSES:
ERROR: external_pause not valid - PAUSE|6666
ERROR: no user found - 6666
ERROR: agent_user is not logged in - 6666
SUCCESS: external_pause function set - PAUSE|1232020456|6666
--------------------------------------------------------------------------------
external_dial -
DESCRIPTION:
Places a manual dial phone call on the agent screen, you can define whether to search for the lead in the existing database or not and you can define the phone_code and the number to dial. This action will pause the agent after their current call, enter in the information to place the call, and dialing the call on the agent screen.
VALUES:
value -
Any valid phone number (7275551212)
phone_code -
Any valid phone country code (1 for USA/Canada, 44 for UK, etc...)
search -
YES - perform a search in the campaign-defined vicidial_list list for this phone number and bring up that lead
NO - do not search, create a new vicidial_list record for the call
preview -
YES - preview the lead in the vicidial screen without dialing
NO - do not preview the lead, place call immediately
focus -
YES - change the focus of the screen to the vicidial.php agent interface, brings up an alert in the browser window
NO - do not change focus
vendor_id -
Any valid Vendor lead code
dial_prefix -
OPTIONAL, any dial prefix that you want to add to the beginning of the dial string for this call
group_alias -
OPTIONAL, the outbound callerID(from an existing group-alias) that you want to use for this call
vtiger_callback -
OPTIONAL, YES or NO, will lookup the phone number and Vtiger account ID from the provided Event ID
alt_user -
OPTIONAL, instead of agent_user, this is to lookup the agent_user using the vicidial_users.custom_three field
EXAMPLE URLS:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_dial&value=7275551212&phone_code=1&search=YES&preview=NO&focus=YES
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_dial&value=7275551212&phone_code=1&search=YES&preview=NO&focus=YES&dial_prefix=88&group_alias=DEFAULT
RESPONSES:
ERROR: external_dial not valid - 7275551212|1|YES|6666
ERROR: no user found - 6666
ERROR: agent_user is not logged in - 6666
ERROR: agent_user is not allowed to place manual dial calls - 6666
ERROR: caller_id_number from group_alias is not valid - 6666|TESTING|123
ERROR: group_alias is not valid - 6666|TESTING
ERROR: vtiger callback activity does not exist in vtiger system - 12345
SUCCESS: external_dial function set - 7275551212|6666|1|YES|NO|YES|123456|1232020456|9|TESTING|7275551211
--------------------------------------------------------------------------------
change_ingroups -
DESCRIPTION:
This function will change the selected in-groups for an agent that is logged into a campaign that allows for inbound calls to be handled. Allows the selected in-groups for an agent to be changed while they are logged-in to the ViciDial Agent screen only. Once changed in this way, the agent would need to log out and back in to be able to select in-groups themselves(If Agent Choose In-Groups is enabled for that user). The blended checkbox can also be changed using this function. The API user performing this function must have vicidial_users.change_agent_campaign = 1.
VALUES:
value -
CHANGE - will change all in-groups to those defined in ingroup_choices
REMOVE - will only remove the listed in-groups
ADD - will only add the listed in-groups
blended -
YES - set the agent to take outbound auto-dialed calls (not applicable in MANUAL and INBOUND_MAN dial method campaigns)
NO - set the agent to only take inbound calls
ingroup_choices -
OPTIONAL, a space-delimited(use plusses + in the URL) list of in-groups to allow the agent to take calls from, example: " TEST_IN2 SALESLINE TRAINING_IN -"
set_as_default -
OPTIONAL, YES or NO - overwrites the settings for the agent in the user modification screen, default is NO
EXAMPLE URLS:
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=change_ingroups&value=CHANGE&set_as_default=YES&blended=YES&ingroup_choices=+TEST_IN+SALESLINE+FAKE_IN+-
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=change_ingroups&value=REMOVE&blended=NO&ingroup_choices=+TEST_IN2+TEST_IN4+-
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=change_ingroups&value=ADD&blended=NO&ingroup_choices=+TEST_IN2+-
RESPONSES:
ERROR: change_ingroups not valid - N| TEST_IN SALESLINE -
ERROR: agent_user is not logged in - 6666
ERROR: campaign does not allow inbound calls - 6666
ERROR: user is not allowed to change agent in-groups - 6666|TESTING|123
ERROR: campaign dial_method does not allow outbound autodial - 6666|TESTING
ERROR: ingroup does not exist - FAKE_IN| TEST_IN FAKE_IN SALESLINE -
ERROR: ingroup_choices are required for ADD and REMOVE values - ADD|
SUCCESS: change_ingroups function set - YES| TEST_IN SALESLINE -|6666
--------------------------------------------------------------------------------
st_login_log -
DESCRIPTION:
Looks up the vicidial_users.custom_three field(as "agentId") to associate with a vicidial user ID. If found it will populate the custom_four field with a "teamId" value, then output the vicidial user ID
VALUES:
value -
REQUIRED alphanumeric string for CRM AgentID
vendor_id -
REQUIRED alphanumeric string for CRM TeamID
EXAMPLE URLS:
http://server/agc/api.php?source=test&user=6666&pass=1234&function=st_login_log&value=876543&vendor_id=207
RESPONSES:
ERROR: st_login_log not valid - 6666|207
ERROR: no user found - 6666
SUCCESS: st_login_log user found - 6666
--------------------------------------------------------------------------------
st_get_agent_active_lead -
DESCRIPTION:
Looks up the vicidial_users.custom_three field(as "agentId") to associate with a vicidial user ID. If found it will output the active lead_id and phone number, vendor_lead_code, province, security_phrase and source_id fields.
VALUES:
value -
REQUIRED alphanumeric string for CRM AgentID
vendor_id -
REQUIRED alphanumeric string for CRM TeamID
EXAMPLE URLS:
http://server/agc/api.php?source=test&user=6666&pass=1234&function=st_get_agent_active_lead&value=876543&vendor_id=207
RESPONSES:
ERROR: st_get_agent_active_lead not valid - 6666|207
ERROR: no user found - 6666
ERROR: user not logged in - 6666
ERROR: no active lead found - 6666
SUCCESS: st_get_agent_active_lead lead found - 6666|7275551212|123456|9987-1234765|SK|WILLIAMS|JUH764AJJJ9
--------------------------------------------------------------------------------
Other information:
Example MySQL query options for executing API functions(not available for all functions):
update vicidial_live_agents set external_hangup=1 where user='1000';
update vicidial_live_agents set external_status='A' where user='1000';
Database changes: (these are already in the system, DO NOT RUN THEM)
ALTER TABLE vicidial_live_agents ADD external_hangup VARCHAR(1) default '';
ALTER TABLE vicidial_live_agents ADD external_status VARCHAR(6) default '';
ALTER TABLE vicidial_live_agents ADD external_pause VARCHAR(20) default '';
ALTER TABLE vicidial_live_agents ADD external_dial VARCHAR(100) default '';
ALTER TABLE vicidial_users ADD vdc_agent_api_access ENUM('0','1') default '0';
ALTER TABLE system_settings ADD vdc_agent_api_active ENUM('0','1') default '0';
CREATE TABLE vicidial_api_log (
api_id INT(9) UNSIGNED AUTO_INCREMENT PRIMARY KEY NOT NULL,
user VARCHAR(20) NOT NULL,
api_date DATETIME,
api_script VARCHAR(10),
function VARCHAR(20) NOT NULL,
agent_user VARCHAR(20),
value VARCHAR(255),
result VARCHAR(10),
result_reason VARCHAR(255),
source VARCHAR(20),
data TEXT,
index(api_date)
);
Reference in New Issue View Git Blame Copy Permalink