Agent API

POST Start a session

POST /agents/{id}/sessions

Operation ID: startSession.

Begin an agent session. The endpoint contains the ID of the Salesforce agent. You can find this ID in the URL of the agent details page. When you select the agent from Setup, use the ID at the end of the URL.

Parameters

• id (path, string, required) The ID of the Salesforce agent. You can find this ID in the URL of the agent details page. When you select the agent from Setup, use the ID at the end of the URL.
• Authorization (header, string, required) Authorization information that contains the JWT.
  Example: Bearer •••••.

Request body (required)

Request payload to initiate a session.

Media type: application/json. Schema: StartSessionRequest.

Responses

• 200 Response to a new session.

  Headers:

  • x-session-mode (string) Agent session mode.
    Example: default

  Media type: application/json. Schema: StartSessionSyncResponseMessage.

• 400 Bad Request

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 400,
    "path": "/v6/00DRM00000067To/sessions/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "BadRequestError",
    "message": "Bad Request",
    "timestamp": 1531245973799
  }

• 401 Access bearer token is missing or invalid

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 401,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "UnauthorizedError",
    "message": "Access bearer token is missing or invalid",
    "timestamp": 1531245973799
  }

• 403 User forbidden from accessing the resource

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 403,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "ForbiddenError",
    "message": "User forbidden from accessing the resource",
    "timestamp": 1531245973799
  }

• 404 Resource not found

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 404,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "NotFoundError",
    "message": "Resource not found",
    "timestamp": 1531245973799
  }

• 422 Any exception that occurred during the request execution

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 422,
    "path": "v4.0.0/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "RequestProcessingException",
    "message": "Cannot determine the active version for the agent",
    "timestamp": 1531245973799
  }

• 423 Server is busy and cannot process the request at this time

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 423,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "ServerBusyError",
    "message": "Server is busy and cannot process the request at this time",
    "timestamp": 1531245973799
  }

• 429 Too many requests for the server to handle

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 429,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "TooManyRequestsError",
    "message": "Too many requests for the server to handle",
    "timestamp": 1531245973799
  }

• 503 Service is unavailable possibly because Apex or Flow calls timed out

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.

  Example

  {
    "status": 503,
    "path": "/v1/00DRM00000067To/chatbots/HelloWorldBot/messages",
    "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
    "error": "ServiceUnavailable",
    "message": "Service is unavailable possibly because Apex/Flow calls timed out",
    "timestamp": 1531245973799
  }

• default Something went wrong

  Headers:

  • X-Request-ID (string) Request ID. A UUID in string format to help with request tracking.
    Example: 36a73651-a46d-4d16-9a8a-fd436ed62e1a

  Media type: application/json. Schema: Error.