--- title: "Dokumentation ACD Callback API" canonical: "https://help.telegra.de/space/TAK/9561593220788/Dokumentation%20ACD%20Callback%20API" format: markdown --- # About Zusätzlich zur Standard-HTTP-API bietet das ACD-System auch eine **CallBack-API**. Diese ermöglicht es, **asynchrone Statusmeldungen** zuverlässig an ein Drittsystem zu übermitteln. Für die Nutzung der CallBack-API ist es erforderlich, ein **Servlet oder ein CGI-Skript** auf Deiner Seite zu **implementieren**, um die CallBack-API-Benachrichtigungen vom ACD-System zu empfangen. Die Benachrichtigungen werden **je nach Konfiguration als HTTP-HEAD-, GET- oder PUT-Anfragen** übermittelt. Die ausgehende IP-Adresse ist die **externe IP des sendenden ACD-Systems**. Um diese zu ermitteln, kannst Du einfach Deine acd-Domäne anpingen. Im Folgenden eine Beschreibung der Nachrichtentypen, die die ACD senden kann. Das Unterscheidungsmerkmal ist der Parameter "cmd". # Message types - agentstate - callevent - recordedcall - classificationevent - schedulecallevent - configchanged # Rufnummern Phone numbers can be formatted in three distinct ways: | | | | | --- | --- | --- | | | | **Beispiele** | | **Format setting** | **Description** | **German National Numbers** | **International Numbers** | | **ACD format** | *German national* numbers are prefixed with a leading zero and area code.
*International numbers* are in international format with two leading zeros. | 02212601599 | 0015552243 | | **FQTN with double zero prefix** | All numbers are in international format with two leading zeros. | 00492212601599 | 0015552243 | | **FQTN with plus prefix** | All numbers are in international format, prefixed with “+”. | +492212601599 | +15552243 | # > Macro (anchor) agentstate The agentstate notification provides information on the current state of an agent. **Parameters for agentstate** | **Parameter** | **Value** | **Description** | | --- | --- | --- | | cmd | agentstate | Type of notification. | | agentid | A 6-digit number | The 6-digit agentnumber given by the ACD System. | | mode | 0 / 1 | 0 = Inbound 1 = Outbound | | state | | The current state of the agent. | | hotline | | Optional If "Mode" is 0 (Inbound) and "State" is "Alerting" or "Connected" then this parameter will contain the name of the involved hotline. | | hotlineid | | Optional If "Mode" is 0 (Inbound) and "State" is "Alerting" or "Connected" then this parameter will contain the internal id of the involved hotline. | | group | | Optional If "Mode" is 0 (Inbound) and "State" is "Connected" then this parameter will contain the name of the involved group. | | groupid | | Optional If "Mode" is 0 (Inbound) and "State" is "Connected" then this parameter will contain the internal id of the involved group. | | mandator | | Optional If "Mode" is 1 (Outbound) and the state is not "Outonline" this parameter will contain the name of the dialed mandator. | | mandatorid | | Optional If "Mode" is 1 (Outbound) and the state is not "Outonline" this parameter will contain the internal id of the dialed mandator. | | callingnumber | | Optional If "Mode" is 0 (Inbound) and "State" is "Alerting" or "Connected" then this parameter will contain the number of the caller. If "Mode" is 1 (Outbound) and the state is not "Outonline" this parameter will contain the number the agent. | | callednumber | | Optional If "Mode" is 0 (Inbound) and "State" is "Alerting" or "Connected" then this parameter will contain the dialed service number. If "Mode" is 1 (Outbound) and the state is not "Outonline" this parameter will contain the dialed number. | | dialer | 0 / 1 | If "mode" is 1 and mass calling is going on for the agent, then "dialer" will be set to 1. If on ther other hand the agent has made a simple call, then "dialer" will be 0. This parameter is not set if "mode" is 0. | | requesttext | | Optional If "Mode" is 1 (Outbound) and the state is "Outalerting", "Balerting" or "Outconnect" this parameter will contain information on the dialed number (if configured in the outbound request) | | eventtime | | Timestamp of the signal generation in number of milliseconds since January 1, 1970, 00:00:00 GMT | | agentphonenumber | | The phone number of the agent. | | taskid | 24 characters string | ID of the call (only present if a call is in process e.g. Alerting, Connected, Outalerting, ...) | | customerNumber | | Customer number | | agent_id | | Agent Resource ID | | pause-reason | | If agent state is “paused“ or “outpaused” this parameter will contain the pause reason. | # Inbound and Outbound The possible values for the parameter "state" are divided into inbound and outbound states: # Inbound | **State** | **Description** | | --- | --- | | offline | The agent is not available and can't receive calls. | | online | The agent is available and can receive calls. | | alerting | An incoming call is signalized. | | connected | The agent and the caller are connected | | timeouted | The agent didn't answer an incoming call. | | busy | The agent is busy with a non ACD call, e.g. someone called him directly. | | working | The connected call is finished and the agent can process the call related pieces of information. | | paused | The agent is paused. | # Outbound | **State** | **Description** | | --- | --- | | outonline | The agent is in outbound mode. He will not receive any calls. | | outalerting | First step of an outbound call. An initiated call is signalized to the calling agent. | | outbusy | The agent is busy with a non ACD call, e.g. someone called him directly. | | outtimeouted | The agent didn't answer the initiated call. | | balerting | Second step of an outbound call. The initiated call is ringing at the customer. | | bbusy | The customers number is busy. | | btimeout | The customer didn't answer the call. | | bunassigned | The target number is unassigned. | | bconnected | The customer answers the call. | | outconnect | The Agent and the customer are connected. | | outworking | The connected call is finished and the agent can process the call related pieces of information. | | outpaused | The agent is paused. | # > Macro (anchor) callevent The callevent notification provides information on every call event. **Parameters for callevent** | **Parameter** | **Value** | **Description** | | --- | --- | --- | | cmd | callevent | Type of notification. | | id | | Unique ID of the event. | | taskid | 24 characters string | ID of the call. | | eventtype | | Type of call event. | | eventtime | | Timestamp of the call event. | | hotlineid | | ID of the hotline. | | groupid | | ID of the group. | | agentid | A 6-digit number | The 6-digit agentnumber given by the ACD System. | | mode | 0 / 1 | 0 = Inbound 1 =Outbound | | mailboxid | | ID of the mailbox. | | mandatorid | | ID of the mandator. | | announcementid | | ID of the announcement. | | callingnumber | | The number of the caller. If number suppression is active the last 3 digits are replaced with xxx. | | callednumber | | The dialed number. | | tried | 0 / 1 | Only present if eventtype is "CallEnd", 0 = alerting did not occur 1 = alerting occured | | connected | 0 / 1 | Only present if eventtype is "CallEnd", 0 = connected did not occur 1 = connected occured | | agent_id | | Agent Resource ID | | conf_agent | A 6-digit number | A consultation target 6-digit agentnumber given by the ACD System | | conf_number | | A consultation target external number | | conf_agent_terminated | | The number of the agent who has ended the consultation | | conf_number_terminated | | The external number has ended a consultation | | customerNumber | | Customer number | | target_number | | The destination number while forwarding the call to an external number | | conf_target | | The selected consultation type (agent / group / number). This parameter will be sent after ending the consultation call | | conf_target_id | | The selected consultation target ID when consultation target is agent or group and destination number when consultation target is external number. This parameter will be sent after ending the consultation call | | conf_target_terminated | | This parameter informs which side terminated the consultation call. When consultation target ends the consultation call, the value will be true. Else false. This parameter will be sent after ending the consultation call | | recording | 0 / 1 | recording = 1 – call will be recorded automatically
recording = 0 – call will not be recorded automatically | | callInternal | | This parameter informs, if this call is an internal call between two agents, or not. This parameter will be present both in the outgoing outbound callevent, and in the incoming inbound callevent. | Possible values for the parameter "eventtype" are: | **Eventtype** | **Description** | | --- | --- | | CallStart | First event of a new call. | | Alerting | The connection is being build up. | | Timeout | The target did not answer the call. | | BTimeout | The outbound-target did not answer the call (outbound only). | | Busy | The target is busy. | | BBusy | The outbound-target is busy (outbound only). | | Connected | The caller is connected. | | AConnected | The outbound-agent is connected (outbound only). | | BConnected | The outbound-customer answered the call (outbound only). | | ForwardAgent | The call is fowarded to an agent. | | ForwardGroup | The call is fowarded to a group. | | ForwardHotline | The call is fowarded to a hotline. | | ForwardNumber | The call is fowarded to an external number. | | ConfAgent | A conference with an agent is started. | | ConfGroup | A conference with a group is started. | | ConfNumber | A conference with an external number is started. | | ConfBusy | The target is busy. | | ConfTimeout | The target did not answer the call. | | ConfConnected | The caller is connected. | | ConfEnd | The conference has ended and the customer is talking to the agent. | | WaitingQueue | Call is put in a waitingqueue. | | Mailbox | Call was connected with a mailbox. | | Announcement | Start of an announcement. | | Rejected | Call could not be connected to an acd resource e.g. all agents are busy and the waiting queue is full. | | BadCall | The call could not be connected because of an error in the SS7 protocoll e.g. max hop-counter exceeded. | | CallEnd | Call has ended. | | Holdstart | The call is put on hold by an agent. | | Holdstop | The call is no longer put on hold. | | ConfConnectedWithAgent | The agent transfers the call to another agent and is connected to this agent while the caller waits on hold. | | ConfConnectedWithCaller | The agent has returned to the caller during transfer and the transfer destination is waiting. | | ConfConnectedWithNumber | The agent transfers the call to an external number and is connected to this number while the caller waits on hold. | | ConfConference | The agent is connected to both destinations and starts a conference. | | ConfTransfer | The agent transfers the call to destination. | | Working | The agent is in the wrap-up time of an incoming call. | | OutWorking | The agent is in the wrap-up time of an outgoing call. | | Recording | Call will be recorded automatically | # > Macro (anchor) recordedcall The recordedcall notification provides information on a currently recorded call. **Parameters for recordedcall** | Parameter | Value | Description | | --- | --- | --- | | cmd | recordedcall | Type of notification. | | taskid | 24 characters string | ID of the call. | | agentid | A 6-digit number | The 6-digit agentnumber given by the ACD System. | | mode | 0 / 1 | 0 = Inbound 1 = Outbound | | eventtime | | Timestamp when the recording started. | | agent_id | | Agent Resource ID | | customerNumber | | Customer number | # > Macro (anchor) classificationevent The classificationevent notification provides information on every classification-event. **Parameters for classificationevent** | **Parameter** | **Value** | **Description** | | --- | --- | --- | | cmd | classificationevent | Type of notification. | | callid | A number | ID of the call. | | timestamp | | Timestamp of the actual moment at which the call was classified by the agent. | | agent | A 6-digit number | The 6-digit agentnumber given by the ACD System. | | classificationreason | | The actual classification. | | hotlineid | A number | (Optional, sent only if mode is 0 (which means inbound)) The hotlinenumber given by the ACD System. | | mandatorid | A number | (Optional, sent only if mode is 1 (which means outbound)) The mandatornumber given by the ACD System. | | classificationcategoryid | A number | The classificationcategorynumber given by the ACD System. | | mode | 0 / 1 | 0 = Inbound 1 = Outbound | | agent_id | | Agent Resource ID | | customerNumber | | Customer number | | eventtime | | Timestamp of the actual moment at which the call was classified by the agent. | # > Macro (anchor) schedulecallevent The schedulecallevent notification provides information on a call which has just been scheduled. **Parameters for schedulecallevent** | **Parameter** | **Value** | **Description** | | --- | --- | --- | | cmd | schedulecallevent | Type of notification. | | scheduleid | | The unique id of the schedule call. | | agentid | | The unique id of the agent as given by the ACD System. | | callednumber | | the called number | | timefrom | | Timestamp as HH:MM e.g. 17:20 | | timeto | | Timestamp as HH:MM e.g. 17:20 | | weekdays | 0/1 | Flag whether the call is planned for week days | | saturday | 0/1 | Flag whether the call is planned for Saturdays | | sunday | 0/1 | Flag whether the call is planned for Sundays | | nextretrystartdate | | nextretrystartdate and nextretryenddate forms an interval between which there will be an attempt to initiate the call. Date as YYYY-MM-DD HH:MM | | nextretryenddate | | See nextretrystartdate. Date as YYYY-MM-DD HH:MM | | agenttype | | ONLY_AGENT or EVERYONE | | requesttext | | The request text. | | schedulestartdates | | The dates at which the call has been scheduled. (The different dates are seperated by a semicolon ';') | | agent_id | | Agent Resource ID | | customerNumber | | Customer number | | eventtime | | Timestamp of the signal generation in number of milliseconds since January 1, 1970, 00:00:00 GMT | # > Macro (anchor) configchanged The configchanged notification provides information whenever the configuration of one of the following items has changed: - agent - group - hotline - mandator - pause reason - classificator **Parameters for configchanged** | **Parameter** | **Value** | **Description** | | --- | --- | --- | | cmd | configchanged | Type of notification. | | action | | name of the action within the ACD system. | | type | | The item that has changed. See the list above. | | secondtype | | Is set if the action has changed more than an item. Can be agent, group, hotline or mandator. | | customerNumber | | Customer number | | eventtime | | Timestamp of the signal generation in number of milliseconds since January 1, 1970, 00:00:00 GMT |