Enhanced Chat Configuration API Endpoints

GET Determines whether service reps are available to accept new chats based on the criteria specified in the channel settings.

GET /embeddedservice/v2/agent-availability

Operation ID: getAgentAvailability. Tags: agentAvailabilityV2.

Before you use this endpoint, an admin must enable Chat Button visibility in Setup. See Control Chat Button Visibility in Enhanced Chat for more information.

Salesforce uses the routing type setting to determine whether to check the primary or fallback queue for agent availability:

• If routing is queue-based (Routing Type is Omni-Queue), Salesforce checks the Queue for agent availability.
• If routing is based on an Omni-Channel flow (Routing Type is Omni-Flow), Salesforce checks the fallback queue for agent availability.
• If routing is directed to an Agentforce Service Agent (Routing Type is Agentforce Service Agent), Salesforce checks the fallback queue for agent availability.

Parameters

• orgId (query, string, required) The 15-character org ID of the Salesforce org where Enhanced Chat is set up.
• esConfigName (query, string, required)

  The API name of the Enhanced Chat Embedded Service deployment. The name can contain alphanumeric characters and underscores, and must begin with a letter. The deployment type that's associated with the esDeveloperName deployment must match the deploymentType in the access token.

  Verify that the Embedded Service deployment is configured to support the request.

  • The deployment type for the Embedded Service deployment must be set to Custom Client. If properly configured, after you send the request, deploymentType in the response will be set to api. If deploymentType isn't set to api, create an Embedded Service deployment or use another deployment with deployment type set to Custom Client. See Configure a Custom Client Deployment for Enhanced Chat for more information.

Responses

• 200 Successful Request

  Media type: application/json. Schema: AgentAvailabilityResponse.

• 400 Bad Request

  Media type: application/json. Schema: Error.

  Example: invalidConfigName Invalid Embedded Service configuration name

  {
    "success": false,
    "error": {
      "errorCode": "BAD_REQUEST",
      "message": "The Embedded Service configuration name is invalid."
    }
  }

  Example: missingOrgId Missing organization ID

  {
    "success": false,
    "error": {
      "errorCode": "BAD_REQUEST",
      "message": "Specify a valid organization ID."
    }
  }

  Example: invalidOrgId Invalid or deleted organization

  {
    "success": false,
    "error": {
      "errorCode": "BAD_REQUEST",
      "message": "The organization ID is invalid or the organization was deleted."
    }
  }

  Example: edgeNotEnabled Edge not enabled for the organization

  {
    "success": false,
    "error": {
      "errorCode": "BAD_REQUEST",
      "message": "To check agent availability, enable Edge for your organization."
    }
  }

  Example: unsupportedDeploymentType Deployment type not supported

  {
    "success": false,
    "error": {
      "errorCode": "BAD_REQUEST",
      "message": "Agent availability API is not supported for this deployment type."
    }
  }

  Example: invalidParameters Invalid request parameters

  {
    "success": false,
    "error": {
      "errorCode": "INVALID_INPUT",
      "message": "The request contains invalid parameters. Check the request and try again."
    }
  }

• 401 Unauthenticated Request
• 403 Unauthorized Request
• 404 Not Found
• 410 Gone

  Media type: application/json. Schema: Error.

• 422 Unprocessable Entity (Setup Errors)

  Media type: application/json. Schema: Error.

  Example: chatButtonVisibilityDisabled Chat Button Visibility setting turned off

  {
    "success": false,
    "error": {
      "errorCode": "SETUP_ERROR",
      "message": "To check agent availability, you must turn on the Chat Button Visibility setting in your Messaging channel settings."
    }
  }

  Example: queueNotConfigured Queue not configured

  {
    "success": false,
    "error": {
      "errorCode": "SETUP_ERROR",
      "message": "You haven't configured a queue in your Messaging channel settings."
    }
  }

• 429

  Too Many Requests.

  Recommendation: If you receive a 429 response, don't use fixed-interval polling. Instead, implement exponential backoff with jitter to avoid further rate limiting.

• 500 Internal Server Error

  Media type: application/json. Schema: Error.

  Example: internalError Internal server error

  {
    "success": false,
    "error": {
      "errorCode": "INTERNAL_ERROR",
      "message": "An internal error occurred. Contact Salesforce Customer Support."
    }
  }

• 503 Service Unavailable
• 504 Gateway Timeout