Public API Versioning and Deprecation

The Chatfuel Public API has a single endpoint, https://panel.chatfuel.com/graphql, with no version number in the URL or headers. Instead of versions, it follows one rule: a published field never changes in a way that breaks existing clients. New capabilities are added alongside the old ones, and anything that has to go is deprecated with a removal date first.

What the public schema guarantees

The public schema is the contract between Chatfuel and your integration. It contains only fields that Chatfuel has explicitly published for external use; the rest of the GraphQL API used by the dashboard is internal and is not available to rely on. Once a field is published, Chatfuel:

• doesn't remove it or rename it without the deprecation process below
• doesn't change its type or make an optional argument required
• doesn't remove input fields you can send

Changes that can happen at any time

Additive changes are not breaking and can ship without notice:

• new queries, mutations, subscriptions and fields
• new optional arguments and input fields
• new values in enums, for example a new Platform or a new sales stage
• new types in unions and new implementations of interfaces, for example a new message type in a conversation

Write clients that tolerate these changes. Select only the fields you need, handle unknown enum values with a default branch, and skip union members and message types your code doesn't know.

How deprecation works

Removing a published field takes three steps:

1. The field gets a GraphQL @deprecated mark with a reason in a fixed format: "Stop using by YYYY-MM-DD. Use X instead." A public replacement ships at the same time, if one is needed. The field keeps working normally.
2. After the stated date, the field is hidden from the public schema. Requests that still select it fail with a validation error.
3. Later, the field is deleted.

The date in the reason is the last day you can count on the field. Until then, migrating to the replacement is safe at any time, because both work in parallel.

How to stay up to date

Deprecations are listed on the reference pages next to the affected operation, with the date and the replacement. Check the reference for the operations your integration uses when you plan maintenance. If a code generator in your project produces types from the schema, regenerate them after updating the schema file you build against, so the compiler shows any deprecated field you still use.

Changes in a published field's behavior that keep its shape, such as a new validation rule, appear as new error codes. Handle unknown error codes as a generic failure, as described in errors.

Common issues

A query that worked yesterday fails because a field is not defined

The field passed its deprecation date and was hidden, or the query selects a field that was never part of the public schema. Compare the query with the reference pages and use the documented replacement.

My code breaks on a value it doesn't know

An enum or union got a new member, which is an additive change. Add a default branch so new values are logged and ignored instead of crashing the integration.