OpenAPI Specification (OAS) for the WhatsApp API

Drawing 1 · Interactive

Will a code generator accept this spec?

Minifying strips the whitespace people need and machines don’t, so every request is smaller.

Try

OpenAPI fragment (JSON)

Pretty-printed JSON.

Parsed and minified

{"paths":{"/{Version}/{Phone-Number-ID}/messages":{"post":{"operationId":"sendMessage","parameters":[{"name":"Version","in":"path","required":true,"schema":{"type":"string"},"example":"v26.0"},{"name":"Phone-Number-ID","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message accepted; returns the wamid"}}}}}}

Bytes before: 700
Bytes after: 353
Saved: 50%

700 → 353 bytes: 50% smaller.
Only whitespace between tokens was removed — spaces inside strings are data and stay.
Minify what goes over the wire; keep the pretty version for people.

Tools parse OpenAPI files strictly before they generate docs or a client. Pick a fragment of a send-message spec: valid JSON parses and minifies, but the one with a trailing comma is rejected, as a generator would reject it.

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) is an open standard for describing HTTP APIs in a machine-readable document, maintained by the OpenAPI Initiative under the Linux Foundation. A single YAML or JSON file covers the whole API: its servers, every path and HTTP method, the parameters and request bodies each one accepts, the response schemas and status codes it returns, and the security schemes it needs. It grew out of the Swagger specification. Version 2.0 is still often called Swagger, while current documents use OpenAPI 3.0 or 3.1.

Because the description is structured, tools can do the repetitive work. They can render interactive reference documentation and generate client libraries and server stubs in dozens of languages. They can spin up mock servers that return example responses, validate requests and responses in tests, and import a whole API into tools such as Postman. In OAS 3.1, schemas are full JSON Schema, so the definition that documents a message object can also validate one.

For WhatsApp, Meta publishes an OpenAPI file for the Business Messaging (WhatsApp) API in its public facebook/openapi repository on GitHub, which its README says is designed for generating SDKs. The file uses OpenAPI 3.1, with https://graph.facebook.com as its server, a bearer-token security scheme and paths templated as /{Version}/{Phone-Number-ID}/messages. It is named after the Graph API version it describes: as of October 2026 that is business-messaging-api_v23.0.yaml, three versions behind the current v26.0. Check which endpoints and fields it covers before you generate code from it.

An OpenAPI document is a contract, not an implementation. An SDK is code generated from that contract or written against it, and a Postman collection is a set of runnable requests. The spec underneath is what keeps all of them consistent with each other and with the REST API they describe.

Key takeaways

The OpenAPI Specification is a vendor-neutral format for describing an HTTP API in YAML or JSON, so that machines can read it.
Meta publishes an OpenAPI 3.1 file for the WhatsApp Business Platform in its facebook/openapi repository on GitHub.
One spec file can generate reference docs, typed clients, mock servers, request validators and contract tests.
An OpenAPI file is the contract and an SDK is code built on it. The spec itself never sends a request.
As of October 2026, Meta's file describes Graph API v23.0, three versions behind v26.0, so check newer fields against the reference docs.

Implementation

The OpenAPI Specification in code

1openapi: 3.1.0
2info:
3  title: WhatsApp Cloud API (excerpt)
4  version: v26.0
5servers:
6  - url: https://graph.facebook.com
7components:
8  securitySchemes:
9    bearerAuth:
10      type: http
11      scheme: bearer
12      description: System user access token
13paths:
14  /{Version}/{Phone-Number-ID}/messages:
15    post:
16      operationId: sendMessage
17      security:
18        - bearerAuth: []
19      parameters:
20        - name: Version
21          in: path
22          required: true
23          schema: { type: string, pattern: '^v[0-9]+\.[0-9]+$' }
24          example: v26.0
25        - name: Phone-Number-ID
26          in: path
27          required: true
28          schema: { type: string, pattern: '^[0-9]+$' }
29      requestBody:
30        required: true
31        content:
32          application/json:
33            schema:
34              type: object
35              required: [messaging_product, to, type]
36              properties:
37                messaging_product: { const: whatsapp }
38                to: { type: string, description: Recipient phone number or WhatsApp ID }
39                type: { enum: [text, template, image, document, interactive] }
40      responses:
41        "200":
42          description: Accepted. The body carries the message ID (wamid).

Simplified for illustration, using the path style of Meta's file. The real v23.0 file runs to more than 30,000 lines of YAML.

Operating sequence

How does the OpenAPI Specification work?

Describe or fetch the contract
Write an openapi.yaml for your own API, or download a published one such as Meta's Business Messaging file from facebook/openapi. Note the openapi version (3.0 or 3.1) and the API version in info.version.
Lint and validate it
Run a linter or validator so that broken $refs, missing schemas and invalid YAML fail fast. A spec that does not parse cannot generate anything.
Generate what you need
Feed the file to a generator for a typed client in TypeScript, Python, Java or Go, to a renderer for reference pages, or to a mock server so front-end work can start before the backend is ready.
Test against the contract
Validate real requests and responses against the schemas in CI. When a field is renamed or a required property goes missing, the contract test fails before customers notice.
Version it with the API
Keep one spec for each API version, and diff the old and new files when you upgrade. For WhatsApp, compare the version in the spec with the Graph API version your code actually calls.

Design intent

Why does the OpenAPI Specification matter?

A WhatsApp integration touches dozens of endpoints: messages, media, templates, phone numbers and business profiles. Each has nested JSON that can change between Graph API versions. With a machine-readable contract, a team can generate a typed client instead of hand-writing request shapes, and catch a misspelt field in CI instead of in production. It can also diff two versions of the spec to see exactly what an upgrade changes. For a platform team supporting many developers, the spec is the single source for docs and examples as well.

Specifications

The OpenAPI Specification: key facts and limits

Current versions: OpenAPI 3.0 and 3.1 (2.0 is "Swagger")
Formats: YAML or JSON
Maintainer: OpenAPI Initiative (Linux Foundation)
Schema language (3.1): JSON Schema 2020-12
Meta's WhatsApp file: facebook/openapi on GitHub, OpenAPI 3.1
Version described (Oct 2026): business-messaging-api_v23.0.yaml; current Graph API is v26.0
Typical outputs: Docs, clients, server stubs, mocks, contract tests

Failure modes

Common mistakes with the OpenAPI Specification

Treating the spec as always current
A published file describes one API version at one moment. Meta's file is named after the Graph API version it covers (v23.0 as of October 2026), while code samples today call v26.0. Compare the two, and check the reference docs for any field or endpoint added since.
Generating a client for the whole surface
A generator run over a very large spec produces thousands of lines you will never call, and slows builds. Generate only the tags or paths you use, or wrap the generated code behind a small interface of your own.
Hand-editing generated code
The next regeneration overwrites your edits. Put customisations such as retries, logging and token refresh in a wrapper or in the generator's templates, never in the generated files.
Confusing validation with behaviour
A request can match the schema and still fail. The 24-hour window, template approval, rate limits and permissions are business rules a spec cannot express. Keep handling API error codes, even with a perfect client.

Example: One typed client for six services in Pune

A Pune fintech's platform team wants a single internal WhatsApp client for six services. They pull Meta's Business Messaging OpenAPI file, keep only the messages, media and template paths they use, and generate a TypeScript client in CI. When a developer passes template.language as a plain string instead of an object with a code, the compiler flags it before review. On each Graph API upgrade, they diff the new spec against the old one and review only the operations that changed.

Recommended practice

Best practices for the OpenAPI Specification

Pin the spec file in your repo and update it deliberately, with the diff visible in the pull request.
Use the spec's examples to seed a mock server for front-end and QA work.
Run a contract test in CI that validates a recorded real response against the schema.
Import the spec into Postman when you want runnable requests alongside the docs.

OAS FAQs

Is OpenAPI the same as Swagger?+

Not quite. Swagger was the specification's original name, up to version 2.0. It was renamed OpenAPI in 2016, and Swagger now names a family of tools that work with OpenAPI documents.

Does Meta publish an OpenAPI spec for the WhatsApp Cloud API?+

Yes. Meta's facebook/openapi repository on GitHub contains an OpenAPI 3.1 file for the Business Messaging (WhatsApp) API, which Meta says is meant for generating SDKs. As of October 2026 it describes Graph API v23.0, so check newer fields against the reference docs.

What is the difference between an OpenAPI spec and an SDK?+

The spec is a description and the SDK is code. An OpenAPI file says what each endpoint accepts and returns. An SDK, often generated from that file, gives you functions that actually make the calls.

Should I write OpenAPI in YAML or JSON?+

Either is valid, and the two are interchangeable. YAML is easier to read and review, and JSON is easier to generate and parse in code. Many teams write in YAML and publish both.

See InfiQ pricing

OpenAPI Specification(OAS)

Will a code generator accept this spec?

What is the OpenAPI Specification?

The OpenAPI Specification in code

How does the OpenAPI Specification work?

Describe or fetch the contract

Lint and validate it

Generate what you need

Test against the contract

Version it with the API

Why does the OpenAPI Specification matter?

The OpenAPI Specification: key facts and limits

Common mistakes with the OpenAPI Specification

Treating the spec as always current

Generating a client for the whole surface

Hand-editing generated code

Confusing validation with behaviour

Example: One typed client for six services in Pune

Best practices for the OpenAPI Specification

OAS FAQs

See how this works on InfiQ

Put OAS to work

See how this works on InfiQ