Task Chain

Task Chains allow you to build your own custom integration to Agent4. The implementation is done utilizing webhooks that you host on your own servers. We offer custom integration options to host this for you and connect to your backend systems. Feel free to reach out to sales@agent4.ai to learn more about this option.

Example Implementation

We've published our ShipStation integration code. It's a great starting point to building your own custom tasks.

Implementation of your webhook

Your webhook will be called for instructions at the beginning of the task and at the end of the task.

Payload

Every call to your webhook will have the following posted JSON object:

    {'name':'first_link',
     'action':"initial",
     'call_from':"+15129999999",
     'call_forwarded_by':"+15128888888",
     'context': {'key':'value'}}

• name: This is the name of the link that you set when you configure the task chain.
• action: The action that is occurring. This will be:
  • initial: Initial call, you should return the initialization prompt. For examples, see our Task Library
  • qualified: The caller successfully completed the task
  • disqualified: The caller was disqualified
  • interrupt: The caller hung up in the middle of the task
• call_from: The number of the calling party
• call_forwarded_by: The number that connected this call to the Agent. (Useful if you have multiple inbound agent numbers)
• context: A dictionary containing data from the interaction. This will only be send in the qualified and disqualified case.

Responses

Your webhook should respond with the following payload:

{
    "key": "6B29FC40-CA47-1067-B31D-00DD010662DA",
    "content": "PROMPT OR RESPONSE",
    "actions": [
        {
            "name": "next_task"
        },
        {
            "name": "switch_task",
            "context": {
                "name": "link2"
            }
        },
        {
            "name": "sms",
            "context": {
                "message": "Text message"
            }
        },
        {
            "name": "transfer_call",
            "context": {
                "number": "+15129999999"
            }
        },
        {
            "name": "end_call"
        },
        {
            "name": "say",
            "context": {
                "content": "some text"
            }
        },
        {
            "name": "email",
            "context": {
                 "email":"send@email.com"
            }
        },
        {
            "name": "set_trigger",
            "context": {
                "trigger": "trigger condition"
            }
        }
    ],
    "state": {
        "global_variable": "value"
    },
    "additional_call_notifications": [
        {
            "email": "send@email.com"
        },
        {
            "webhook": {
                "host": "https://www.example.com/",
                "headers": {"Authorization":"Token 1234"}
            }
        }
    ],
    "qualified_parameters": {
        "properties": {
            "timeslot": {
                "type": "string",
                "description": "The timeslot selected by the user."
            }
        },
        "required": ["timeslot"]
    },
    "disqualified_parameters": {
        "properties": {
            "reason": {
                "type": "string",
                "description": "Reason for disqualification."
            }
        },
        "required": ["reason"]
    },
    "interrupt_parameters": {
        "properties": {
            "reason": {
                "type": "string",
                "description": "Reason for interruption."
            }
        },
        "required": ["reason"]
    }
}

• key: Unique identifier that will remain consistent throughout the call.

• content: If this is the initial webhook action, then return the initial prompt to start the conversation. Otherwise, it will be spoken as delivered.

• actions: This is a list of possible actions that can occur in response:

  • next_task: Moves on to the next task in a task chain.
  • switch_task: Switches to a task specified by its name in the task chain.
  • sms: Sends an SMS message to the caller.
  • transfer_call: Transfers the call to another phone number.
  • end_call: Ends the call with the caller.
  • say: Speaks the given content to the caller.
  • email: Sends an email summarizing the conversation.
  • set_trigger: Sets a specific trigger for future responses.

• state: A dictionary to update the global state.

• additional_call_notifications: A list of additional notifications triggered during after the call has completed:

  • email: Sends an email notification to the specified address.
  • webhook: Sends a webhook notification to the specified host with provided headers.

• qualified_parameters: Defines a JSON schema for parameters that qualify the response:

  • properties: Describes each parameter and its type.
  • required: Lists required parameters.

• disqualified_parameters: Defines a JSON schema for parameters that disqualify the response:

  • properties: Describes each parameter and its type.
  • required: Lists required parameters.

• interrupt_parameters: Defines a JSON schema for parameters for an interrupt call (when the caller hangs up before the task is complete):

  • properties: Describes each parameter and its type.
  • required: Lists required parameters.

Note: qualified_parameters, disqualified_parameters, interrupt_parameters are only valid during the initial call and not for subsequent qualified or disqualified calls.

Configuration and Activation

In the task interface, create a new task and choose the TaskChain type. Then, configure the task.

The trigger should be the phrase or keywords to start the task. The Chain should be a JSON object describing your chain. Here is an example:

[
  {
    "name": "pin_vetting",
    "endpoint": "https://your.webhook"
  },
  {
    "name": "sms_vetting",
    "endpoint": "https://your.webhook"
  },
  {
    "name": "data",
    "endpoint": "https://your.webhook"
  }
]

After that, activate the task and publish your tasks, then give it a try!

Initial testing can be done with just putting text files somewhere to try it out. If you need help, don't hesitate to ask us at support@agent4.ai.