Skip to main content
You may want to ask a human for input for a variety of reasons:
  • Getting consent from humans before performing an action
  • Getting additional information in order to perform an action
  • Asking for clarification
We provide an API that takes a prompt, and returns the human’s immediate next response to that prompt: 
curl -X POST https://api.agentreach.ai/v1/session/agent/message-human-and-get-response \
  -H "Authorization: Bearer <Agent API Key>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "<sessionId>", "message": "<message>"}'
The API returns a JSON object with the following fields: 
{
    "shouldRetry": boolean,
    "message": string
}
  • If shouldRetry is set to true, it means you should retry this API. You do not need to wait before retrying since the API does some waiting itself. This is usually true when we are waiting for the human to respond to your message. The session state can be “stuck” in this state for a long time depending on when the human responds, so you should keep retrying and not continue your agent workflow.
  • If shouldRetry is set to false, it means the message the human has responded with the message available in the response body, and you can continue your agent workflow.
Handling error status codes:
  • It can also return a 400 status code if the session is in a different state (like if you had requested for a human input with a different prompt and are still waiting for that). Therefore, we recommend that you only continue your agent workflow once the API has returned a 200 status code.
  • If the API returns a 5xx error, or is down, then you should wait for up to 1 second and try again.