Versioning

Ada’s APIs use path-based versioning, e.g., https://{bot-handle}.ada.support/api/end-users/v1.

We use only major versions, and do not expose minor versions:

• A new major version entails breaking changes.
• Minor additive changes will not be reflected in the API version, but will be detailed in Ada’s changelog as well as the API specification.

Authentication

To connect with the End Users API, you need an API key that you’ll include in the header of your requests. To learn how to generate an API key, see Authorize API integrations.

Rate limits

The End Users API is subject to per-second and per-day rate limiting. Exceeding the rate limit will return a 429-Too Many Requests response status code.

Rate limits ensure the stability of Ada's infrastructure and the best experience for all clients. When calling the End Users API, you should implement 429 retry logic using exponential backoff and jitter.

Data limits

Payloads sent to the End Users API are limited to 4 KB. Payloads exceeding 4 KB will return a 413-Content Too Large status code.

Pagination

The End Users API supports cursor-based pagination. Cursor-based pagination works by returning a pointer to a specific item in the dataset. On subsequent requests, the server returns results after the given pointer. Optionally, the End Users API supports a limit query parameter to control the number of records returned by the request.

Testing

Test with Swagger UI

You can make API requests directly from the Swagger UI.

1. In the page URL, update the handle from example to your bot handle.
2. At the top of the page, in the handle field, replace example with your bot handle.
3. Click the Authorize button. In the Available authorizations window, paste in your End Users API key, and click Authorize, then Close.
4. Expand any endpoint and click Try it out.
5. Enter any required parameters and/or a request body, as required for the endpoint.
6. Click Execute.

📘

Some requests (e.g. PATCH) may require you to input your bot handle as a server variable within the request UI.

Test with Postman

You can import the End User API OpenAPI specification to Postman. Ensure you set Parameter generation to "Example" instead of "Schema" when importing the spec.

The API specification in JSON format can be found here.

Learn more about importing data to Postman.

Webhooks

Ada webhooks

Use webhooks to extend Ada’s platform and integrate your systems more deeply with Ada. Webhooks are how Ada notifies external systems of events that occur inside Ada. You can bring your own webhook endpoint or use Ada’s webhooks UI to test one out with Svix Play.

📘

Svix Play is strictly for testing purposes only. These endpoints should not be considered reliable for use in a production environment.

Ada only supports HTTPS webhook endpoints.

If messages to a particular endpoint have been consistently failing for one week, Ada will automatically disable the endpoint. You can re-enable it from the webhooks UI.

End Users webhook events

The End Users API supports two types of events, which you can subscribe to via the Event Catalog in the Webhooks dashboard:

• v1.end_user.created: triggered when new users are created through any of Ada’s supported channels. Note that your bot’s customer persistence setting affects the rate at which new customers are created.

• v1.end_user.updated: triggered whenever a value on the end user’s profile changes. Some of the ways in which profile values can change include:

  • End Users API (PATCH)
  • Metavariable value is updated through any of Ada’s supported channels (e.g. setMetafields on embed)
  • User profile fields are mapped from Sunshine Conversations to the Ada End User profile (depending on your configuration)

  📘

  Changes to values in system.properties or changes to Ada's metavariables (browser, user_agent, etc.) will not generate end_user.updated events.

The End Users API webhooks schemas are documented in the API spec.

Changes that don't trigger events

You should be aware that some changes don't trigger end_user.updated events:

• Changes to values in system.properties

• Changes to Ada's metavariables, including:

  • ip_address
  • user_agent
  • device
  • browser
  • browser_version
  • introshown
  • initialurl
  • last_answer_id
  • last_question_asked
  • sunshine_first_message_id
  • sunshine_end_user_channel
  • sunshine_signed_up_at
  • channel_last_seen
  • channel_active
  • channel_status
  • sunshine_conversation_started
  • sunshine_user_id
  • sunshine_facebook_page_id
  • sunshine_whatsapp_channel_display_name
  • sunshine_whatsapp_channel_phone_number

  Note that the specific metavariables in this list are subject to change.