Agent API
Agent API (v1.0.0)
Download OpenAPI specification:Download
Use Agent API to communicate with AI agents in your org. Get access to your topics and actions in Agentforce by sending messages to AI agents. Create a Salesforce app in your org, generate a token, and then start using the API. To onboard to this API, see Get Started with the Agent API and Agent API Examples.
The quickest way to get started with the Agent API is with our Postman collection.
- Start a Session: Start a session with an agent.
- Send a Message (sync): Send a sync message to the agent on an active session.
- Send a Message (streaming): Send a streaming message to the agent on an active session.
- End a Session: End a session.
- Submit Feedback: Submit feedback for a message.
Start a session
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.
path Parameters
| id required | string 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. |
header Parameters
| Authorization required | string Example: Bearer ••••• Authorization information that contains the JWT. |
Request Body schema: application/jsonrequired
Request payload to initiate a session.
| externalSessionKey required | string (ExternalSessionKey) UUID that you provide for the conversation. You can use this parameter to trace the conversation in your agent's event logs. |
required | object (InstanceConfig) API configuration parameters. |
| tz | string Client timezone where the customer starts the chat. Uses the tz database timezone format. Can be null. |
Array of objects (Variables) Array of custom and context agent variables passed to the agent during a session. See Agent Variables. Many variables are read-only and can only be set during the start session call. By default, context variables (which have the | |
| featureSupport | string (SessionFeature) Enum: "Sync" "Streaming" Defines how the session supports message processing. |
object (StreamingCapability) Describes the streaming capabilities. | |
| bypassUser | boolean Indicates whether to use the agent-assigned user instead of the logged in user. If set to |
Responses
Request samples
- Payload
{- "externalSessionKey": "57904eb6-5352-4c5e-adf6-5f100572cf5d",
- "tz": "America/Los_Angeles",
- "variables": [
- {
- "name": "$Context.EndUserLanguage",
- "type": "Text",
- "value": "en_US"
}
], - "featureSupport": "Sync",
- "streamingCapabilities": {
- "chunkTypes": [
- "Text"
]
}, - "bypassUser": "true"
}Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 423
- 429
- 503
- default
{- "sessionId": "57904eb6-5352-4c5e-adf6-5f100572cf5d",
- "_links": {
}, - "messages": [
- {
- "id": "a133c185-73a7-4adf-b6d9-b7fd62babb4e",
- "type": "Inform"
}
]
}Send a message (synchronous)
Send a synchronous message to the agent on an active session. The endpoint contains the ID of the active session, which was returned in the response of the Start Session call.
path Parameters
| session-id required | string The ID of the active session, which is the |
header Parameters
| Authorization required | string Example: Bearer ••••• Authorization information that contains the JWT. |
Request Body schema: application/jsonrequired
Request payload to continue the chat.
required | object (AbstractRequestMessage) Represents the message to be sent. Can be one of the following request message types: Text, Reply, Cancel, TransferFailed, TransferSucceeded, PlanTemplate. |
Array of objects (Variables) Array of custom and context agent variables passed to the agent during a session. See Agent Variables. Many variables are read-only and can only be set during the start session call. By default, context variables (which have the |
Responses
Request samples
- Payload
{- "message": {
- "type": "Text",
- "sequenceId": 1,
- "text": "Can you provide a summary of my orders?"
}, - "variables": [
- {
- "name": "$Context.EndUserLanguage",
- "type": "Text",
- "value": "en_US"
}
]
}Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 423
- 429
- 503
- default
{- "messages": [
- {
- "id": "a133c185-73a7-4adf-b6d9-b7fd62babb4e",
- "type": "Inform"
}
], - "_links": {
}
}Send a message (streaming)
Send a streaming message to the agent on an active session. Returns an SSE stream in the response. The endpoint contains the ID of the active session, which was returned in the response of the Start Session call.
path Parameters
| session-id required | string The ID of the active session, which is the |
header Parameters
| Authorization required | string Example: Bearer ••••• Authorization information that contains the JWT. |
| Accept required | string Example: text/event-stream Indicates which content type the sender is able to understand. For this endpoint, specify |
Request Body schema: application/jsonrequired
Request payload to continue the chat.
required | object (AbstractRequestMessage) Represents the message to be sent. Can be one of the following request message types: Text, Reply, Cancel, TransferFailed, TransferSucceeded, PlanTemplate. |
Array of objects (Variables) Array of custom and context agent variables passed to the agent during a session. See Agent Variables. Many variables are read-only and can only be set during the start session call. By default, context variables (which have the |
Responses
Request samples
- Payload
{- "message": {
- "type": "Text",
- "sequenceId": 1,
- "text": "Can you provide a summary of my orders?"
}, - "variables": [
- {
- "name": "$Context.EndUserLanguage",
- "type": "Text",
- "value": "en_US"
}
]
}Response samples
- 400
- 401
- 403
- 404
- 422
- 423
- 429
- 503
- default
{- "status": 400,
- "path": "/v6/00DRM00000067To/sessions/HelloWorldBot/messages",
- "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
- "error": "BadRequestError",
- "message": "Bad Request",
- "timestamp": 1531245973799
}End an active session
Send a message to the agent to end a session. The endpoint contains the ID of the active session, which was returned in the response of the Start Session call.
path Parameters
| session-id required | string The ID of the active session, which is the |
header Parameters
| Authorization required | string Example: Bearer ••••• Authorization information that contains the JWT. |
| x-session-end-reason required | string (EndSessionReason) Enum: "UserRequest" "Transfer" "Expiration" "Error" "Other" Example: UserRequest The reason the session ended. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 423
- 429
- 503
- default
{- "messages": [
- {
- "id": "a133c185-73a7-4adf-b6d9-b7fd62babb4e",
- "type": "Inform"
}
], - "_links": {
}
}Submit feedback
Submit feedback for a message. Feedback data is stored in Data 360.
path Parameters
| session-id required | string The ID of the session, which is the |
header Parameters
| Authorization required | string Example: Bearer ••••• Authorization information that contains the JWT. |
Request Body schema: application/jsonrequired
The feedback payload.
| feedbackId required | string (FeedbackId) Unique ID to identify the generation. Used to submit feedback. |
| feedback required | string (FeedbackRating) Enum: "GOOD" "BAD" Feedback rating, suggesting a thumbs up or thumbs down. |
| text | string Textual representation of user feedback. |
object <= 10 properties Additional details to provide as key value pairs. |
Responses
Request samples
- Payload
{- "feedbackId": "9247bbd8-5ed9-11ee-8c99-0242ac120002",
- "feedback": "GOOD",
- "text": "Email looks great.",
- "details": {
- "userId": "uid"
}
}Response samples
- 400
- 401
- 403
- 404
- 422
- 423
- 429
- 503
- default
{- "status": 400,
- "path": "/v6/00DRM00000067To/sessions/HelloWorldBot/messages",
- "requestId": "19c056ab-d909-49df-b976-65e56b6ab214",
- "error": "BadRequestError",
- "message": "Bad Request",
- "timestamp": 1531245973799
}