Skip to content
The InfiQ GlossaryFeature

Graph API & SDKs

Graph API

Meta's versioned HTTP API at graph.facebook.com, modelled as nodes, edges and fields, through which the WhatsApp Cloud API and its management APIs are served.

Also called: Meta Graph API · Facebook Graph API · graph.facebook.com

InfiQ Glossaryreviewed Foundation

What is the Graph API?

The Graph API is Meta's main programming interface, served over HTTPS from graph.facebook.com. It models everything — users, pages, apps, businesses and, for WhatsApp, WhatsApp Business Accounts (WABAs), phone numbers, message templates and media — as a graph: nodes are individual objects with an ID, edges are the connections between them, and fields are the properties a node carries. The WhatsApp Cloud API is not a separate server; it is a set of nodes and edges on the Graph API.

Requests follow one pattern: https://graph.facebook.com/{version}/{node-id}/{edge}. A GET on a node reads its fields (GET /v26.0/{PHONE_NUMBER_ID}?fields=quality_rating), a GET on an edge lists connected objects (GET /v26.0/{WABA_ID}/message_templates), and a POST to an edge creates something — POST /v26.0/{PHONE_NUMBER_ID}/messages sends a message and POST /v26.0/{PHONE_NUMBER_ID}/media uploads a file. Every call is authorised with an Access Token in the Authorization: Bearer header and pinned to a dated version in the path.

Three WhatsApp-related APIs live on it: the Cloud API for messaging (messages, media, registration), the WhatsApp Business Management API for accounts, phone numbers and templates, and the Business Management API for business portfolios, system users and asset sharing. Compared with a generic REST API, the Graph API adds an object-graph model with uniform IDs, Field Expansion to choose and nest the properties returned, standard cursor paging on list edges, and a single error envelope carrying Meta's own error codes.

Key takeaways

  • The Graph API is Meta's HTTP API at graph.facebook.com, built from nodes (objects), edges (connections) and fields (properties).
  • The WhatsApp Cloud API, the WhatsApp Business Management API and the Business Management API are all served through it.
  • Every call names a version in its path — v26.0 is the current Graph API version — and carries a bearer access token.
  • Errors come back as one JSON error object with a numeric code and an fbtrace_id; build your handling around the code.
  • Sending a WhatsApp message is a POST to the phone number node's messages edge: /{PHONE_NUMBER_ID}/messages.

Figure 1

Send a Graph API read and watch the reply

2 / 2
GEThttps://graph.facebook.com/v26.0/106540352242922?fields=display_phone_number,verified_name,quality_rating

GET 200 in 420 ms

Request

2 headers
GET /v26.0/106540352242922?fields=display_phone_number,verified_name,quality_rating HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
facebook-api-version: v26.0
{
"display_phone_number": "+91 98765 43210",
"verified_name": "Demo Tutorials",
"quality_rating": "GREEN",
"id": "106540352242922"
}
Try another response
A real-shaped GET on a WhatsApp phone number node with a fields filter. Press Send to watch it travel, then switch to the error responses for an expired token or an unknown field.

Response: 200 OK after 420 ms.

Why it matters

Why does the Graph API matter?

Knowing the Graph API's model makes every WhatsApp endpoint predictable. Once you know that a phone number is a node and messages, media and register are edges on it, the documentation stops being a list of unrelated URLs: you can guess paths, read any object's fields with one pattern, debug with the same tools (Graph API Explorer, Access Token Debugger) and handle errors in one place. It also explains behaviour that surprises newcomers — dated versions that expire, tokens and permissions shared with the rest of Meta's platform, and rate limits applied per app and per business.

How does the Graph API work?

  1. Every object has an ID

    WABAs, phone numbers, templates, media files and business portfolios each have a numeric ID. You address an object by putting its ID in the path — for a sending number, its Phone Number ID.

  2. Edges connect objects

    A node's edges list or create related objects: a WABA's phone_numbers and message_templates, a phone number's messages and media. GET reads an edge; POST to it creates.

  3. Fields shape responses

    Add fields= to choose properties and expand edges in one call. Unrequested fields are left out, and some — such as health_status — appear only when you ask for them.

  4. Versions pin behaviour

    The path starts with a version such as /v26.0/. Under Graph API Versioning each version keeps working for at least two years, so you upgrade on your schedule rather than on Meta's release day.

  5. Tokens and permissions authorise

    A bearer token carries the permissions granted to your app: whatsapp_business_messaging to send, whatsapp_business_management to manage numbers and templates, business_management for portfolio assets.

  6. One error envelope

    Failures return an error object with message, type, code, usually error_data.details for WhatsApp, and an fbtrace_id to quote to Meta support.

Example: Mapping a first integration onto the graph

A Hyderabad edtech team integrating WhatsApp sketches its calls as graph operations before writing code. Onboarding gives it a WABA ID and a phone number ID. A GET on the WABA's message_templates edge lists approved templates; a POST to the phone number's messages edge sends an admission-reminder template; a GET on the phone number with fields=quality_rating,health_status feeds an ops dashboard. All three share one base URL, one version, one bearer token and one error handler, so the team writes a single small Graph client instead of three separate integrations.

— Mapping a first integration onto the graph

The Graph API in code

GET /v26.0/{PHONE_NUMBER_ID}?fields=display_phone_number,quality_rating HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}
 
HTTP/1.1 200 OK
Content-Type: application/json
facebook-api-version: v26.0
 
{"display_phone_number":"+91 98765 43210","quality_rating":"GREEN","id":"{PHONE_NUMBER_ID}"}

A read on a phone number node: version in the path, token in a header, only the requested fields back.

Common mistakes with the Graph API

  • Leaving the version out

    Unversioned calls use the app's default version from the App Dashboard, which may be old and changes when someone upgrades it. Always put the version, such as /v26.0/, in the path.

  • Branching on HTTP status alone

    Meta recommends building error handling around the error code and details, because many different problems share one HTTP 400. Parse the body's error object and log fbtrace_id.

  • Calling the right edge on the wrong node

    WABA IDs, phone number IDs and business IDs are all long numbers. POST /{WABA_ID}/messages fails because messages hang off the phone number node. Name variables by node type.

  • Expecting the Graph API to push data

    Graph calls are request–response only. Inbound messages and delivery statuses arrive through webhooks, not through any endpoint you can poll, so a send-only integration never sees replies.

Best practices for the Graph API

  • Wrap the Graph API in one small client that sets the version, token and error parsing once.
  • Keep the version in configuration so an upgrade is a one-line change you can test.
  • Try any new call in the Graph API Explorer before writing code for it.
  • Store fbtrace_id with every failed request — Meta support asks for it first.

Graph API FAQs

Is the WhatsApp Cloud API part of the Graph API?
Yes. The Cloud API is a set of nodes and edges on graph.facebook.com — for example POST /{PHONE_NUMBER_ID}/messages — using the same versions, tokens and error format as the rest of the Graph API.
Is the Graph API a REST API?
It is HTTP and JSON with resource-style URLs, so it behaves much like REST. What it adds is an object graph: every object has an ID, connections are edges, and the fields parameter chooses and nests properties in a standard way.
Is the Graph API the same as GraphQL?
No. Despite the name it is not GraphQL — there is no query language or single query endpoint. You call URL paths with GET, POST and DELETE and shape responses with the fields parameter.
Which Graph API version should I use for WhatsApp?
Use the current version, v26.0, for new work and pin it in the path. Existing integrations can stay on an older version while it is supported, but should test and upgrade well before its end date.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms