protocol

Ably Realtime Protocol

Error Codes

Ably's client library SDKs, and the core realtime platform, use common error codes. The canonical registry of these codes is maintained as one Markdown file per code in errors/codes; the machine-readable errors.json in this directory — a map of each code to its identifier, title and summary — is generated from that registry (via npm run generate:errors) and must not be edited by hand.

In addition, a list of error codes and corresponding support articles to help understand how to resolve common problems relating to these error codes can be seen in errorsHelp.json. This ensures that with every Ably error message that includes a help link for the error in the format https://help.ably.io/error/{{ERROR_CODE}}, the user is taken to a relevant FAQ if it exists, and if one does not exist, we record the number of times that error code has been visited so that the docs/support team can work on adding relevant documentation. See the ably/help repository (internal), the "simple help redirect site".

If you need help understanding any error codes, or need technical support, please visit the Ably support desk.

Agents

A list of agents announced by Ably client libraries can be found in agents.json.

See RSC7d for more information on the Agent library identifier and the Ably-Agent HTTP header.

Agent CSV Data

Agent metadata and release information is automatically exported to CSV files and published to S3 for analytics and reporting purposes. These files are publicly accessible at:

• Agent Metadata: https://schemas.ably.com/csv/agents/agents.csv

  • Contains all agent metadata from agents.json (identifier, type, versioned, source, product, name)

• Release Data: https://schemas.ably.com/csv/agents/agent-release-data.csv

  • Contains GitHub release information for all SDK and wrapper agents
  • Includes version, release dates, support/deprecation dates, and AI-generated release summaries

The CSV files are automatically regenerated and uploaded:

• Daily at 2 AM UTC (via scheduled workflow)
• When changes are made to protocol/agents.json or the export scripts
• Manually via the Sync Data to S3 workflow

Generating CSV Files Locally

To generate the CSV files locally for testing:

# Generate agent metadata CSV
npm run export:agents

# Generate release data (requires GITHUB_TOKEN and OPENAI_API_KEY in .env)
npm run fetch:agent-releases

The generated files will be created in the data/agents/ directory (which is git-ignored).

Testing S3 Upload Locally

To test the upload configuration without actually uploading to S3:

# Dry-run mode (no AWS credentials required)
npm run upload:s3 -- --dry-run

Note: Actual uploads to S3 require AWS credentials. The production schemas.ably.com bucket uses the ably-sdk-schemas-ably-common IAM role, which is only available in GitHub Actions. Local users typically won't have direct access to upload to the production bucket.

AWS Credentials for Local Upload

If you need to upload to S3 locally (e.g., to a test bucket), you must have AWS CLI installed and configured:

# Install AWS CLI if not already installed
brew install awscli  # macOS
# or
apt-get install awscli  # Ubuntu/Debian

# Configure AWS credentials (creates a 'default' profile)
aws configure

You can also specify a different AWS profile by setting the AWS_PROFILE environment variable in your .env file:

AWS_PROFILE=your-profile-name

For uploading to a different bucket (for testing), set these in your .env:

S3_BUCKET=your-test-bucket
S3_PREFIX=csv/agents
AWS_PROFILE=your-profile-name

Adding New Agents

When a new agent is added to a client library, add a corresponding entry to agents.json using the schema defined in agents-schema.json, and open a pull request against the main branch with those changes.

Analytics pipeline support

The agents are replicated in the analytics pipeline that processes agent headers. See udtf_parse_ably_agent.py.

Once the pull request is merged into main, notify the Data / Infrastructure team of the changes to agents.json so that they can update the analytics data pipeine to support the newly added agents.

Additional Notes on Agents

The following table adds more contextual detail for some agent identifiers, where:

• The table does not include those where type is sdk. In these cases there is always only a single emitter, where the identifier value matches the name of the SDK source code repository in the ably GitHub org - e.g. identifier ably-js is emitted by ably-js.
• The table rows are sorted alphabetically by identifier.
• It intentionally does not include columns that repeat information that is already canonically defined in agents.json (e.g. values of versioned and type).
• The 'Emitters' column provides links to SDK source code repositories which directly emit this identifier.

Identifier	Emitters
ably-asset-tracking-android	ably-asset-tracking-android
ably-asset-tracking-swift	ably-asset-tracking-swift
ably-cli	ably-cli command line CLI too
ably-flutter	ably-flutter
ably-ruby-rest	ably-ruby
android	ably-java, ably-dotnet
browser	ably-js
chat-js	ably-chat-js
chat-react	ably-chat-js
chat-kotlin	ably-chat-kotlin
chat-swift	ably-chat-swift
chat-react-ui-components	ably-chat-react-ui-components (Deprecated, use chat-react-ui-kit
chat-react-ui-kit	ably-chat-react-ui-kit
dart	ably-flutter
darwin	ably-go
dotnet-framework	ably-dotnet
dotnet-standard	ably-dotnet
go	ably-go
iOS	ably-cocoa, ably-dotnet
jre	ably-java
kafka-connect-ably	kafka-connect-ably
laravel	ably-php
laravel-broadcaster	ably-php
laravel-echo	ably-js
linux	ably-dotnet, ably-go
macOS	ably-cocoa, ably-dotnet
nativescript	ably-js
nodejs	ably-js
php	ably-php
python	ably-python
react-hooks	react-hooks
react-native	ably-js
ruby	ably-ruby
spaces	spaces
models	models
tvOS	ably-cocoa
unity	ably-dotnet
uwp	ably-dotnet
watchOS	ably-cocoa
windows	ably-dotnet, ably-go
xamarin	ably-dotnet

ablyLibMappings

The ablyLibMappings field in agents.json provides continuity for SDKs that continue to send the deprecated X-Ably-Lib header, which was not capable of sending the extra information we now send in the Ably-Agent header. Each entry in ablyLibMappings is used server-side to map an old X-Ably-Lib value to its equivalent new Ably-Agent value.

For example, an old client that sends the header X-Ably-Lib: js-web-1.1.0 will be mapped to Ably-Agent: ably-js/1.1.0 browser based on the js-web entry, and then handled as if it sent that Ably-Agent header directly.

It is not expected that any new mappings will be added, since we shouldn't be sending any new types of values using the deprecated X-Ably-Lib header, any newly released code should be sending the Ably-Agent header instead.

Guidance adding custom agents to SDKs and/or Control API

Adding Custom Agent Headers

When implementing Ably functionality in tools, wrappers, or integrations, it's important to add custom agent headers to help track usage and debug issues. Here's how to add agent headers in different contexts:

1. Using Ably SDK (JavaScript/TypeScript)

For REST or Realtime clients, use the agents property in ClientOptions:

const client = new Ably.Realtime({
  key: 'your-api-key',
  agents: {
    'your-agent-name': 'version'  // e.g., 'ably-cli': '0.7.7'
  }
});

1. Direct HTTP Requests

When making direct HTTP requests to Ably APIs, add the Ably-Agent header:

fetch('https://api.ably.com/endpoint', {
  headers: {
    'Authorization': 'Bearer your-token',
    'Ably-Agent': 'your-agent-name/version'  // e.g., 'ably-cli/0.7.7'
  }
});

1. Agent Naming Conventions

• Use lowercase kebab-case for agent names (e.g., ably-cli, my-integration)
• Include version numbers in semantic versioning format (e.g., 1.2.3)
• For wrappers/tools, use descriptive names that indicate the tool's purpose

1. Adding to agents.json

To officially register your agent, add it to agents.json:

{
  "identifier": "your-agent-name",
  "versioned": true,
  "type": "wrapper"  // or "tool", "integration", etc.
}

1. Testing Agent Headers

• For SDK usage: The agent will be automatically included in all REST and WebSocket requests
• For HTTP requests: Verify the header is present using network inspection tools
• Consider adding tests to ensure the agent header is included correctly

1. Version Management

• Consider reading version from your local package
• For compiled/distributed tools, you may need to hardcode the version
• Remember to update the version when releasing new versions of your tool