A session is started when a user messages your agent in a new “thread”. In platforms that support multi threaded chat UI (like slack or email), this will be a new email or slack thread. In platforms that are single threaded (like whatsapp or SMS), this will be a new message in the chat if a session is not already active.

When this happens, AgentReach will call your registered agent webhook with the following JSON body:

{
	version: number,
    sessionId: string,
    endUserId: string | undefined,
    message: string,
    channel: {
        type: string,
        email?: string,
        slackUserId?: string
    }
}
  • version: This is to identify the version of the request payload. Currently, this is always 1, but you should check it anyway to ensure your agent doesn’t break when there are changes to the payload we send. When we do have multiple versions, and if you send back a 400 status code from your webhook, we will retry with an older enabled version.
  • sessionId: This is the session ID that AgentReach will use to identify the session. You can use this string to query our API to manage this session, or talk to the user.
  • endUserId: This is the user ID identifying the end user who started the session. If this is not known, this field will not be present in the input JSON.
  • message: This is the raw message string sent by the end user to your agent.
  • channel: This is an object containing the type of the communication channel, and the relevant user ID or email for that channel.

It will also contain an authorization header with the Agent API key displayed on your dashboard. See this section on how to secure your webhook to check for the API key.

Once the webhook is called, you can immediately return a 200 response and start your agent workflow in the background. Or you can start your agent workflow and then once it’s over, you can return a 200 response.