Field Expansion

1. $ step 1 — Start from the node

   Pick the object you are reading — a phone number ID, a WABA ID, a template ID — and call it with GET. Without fields, the Graph API returns that node's default set of fields.

2. $ step 2 — List the fields you need

   Add fields= with comma-separated names and no spaces, e.g. fields=display_phone_number,quality_rating,name_status. The response holds those fields plus id, which is always returned.

3. $ step 3 — Expand an edge with braces

   Name an edge and put its fields in curly braces: phone_numbers{display_phone_number,quality_rating}. Each expanded edge comes back as an object with a data array and paging cursors.

4. $ step 4 — Attach modifiers to the edge

   Add .limit(n) to cap items per page and .after(cursor) to continue a page inside the expansion, e.g. message_templates.limit(20){name,status,category}.

5. $ step 5 — URL-encode the value

   Braces, commas and parentheses must survive the trip. Encode the fields value — curl -G --data-urlencode, or URLSearchParams in code — instead of pasting raw braces into a shell.

Parameter

fields — comma-separated, no spaces

Nested edge syntax

edge{field,field}

Edge modifiers

.limit(n), .after(cursor), .as(alias) where supported

Always returned

id, even when not requested

Expanded edge shape

{ data: [...], paging: { cursors } }

Unknown field

Error 100 — the whole request fails

Nesting depth

No documented limit; very large trees can be rejected

Most WhatsApp management reads — a dashboard of number quality, a list of template statuses, an onboarding check after Embedded Signup — need a handful of fields from many objects. Asking for exactly those fields keeps responses small, cuts round trips (one expanded call instead of one per phone number) and makes your code explicit about what it depends on, so a change to a node's default fields does not silently change your data. It is also the only way to get fields that are not in the default response, such as health_status, which appears only when you request it.

• Pasting raw braces into a shell

  Shells and curl's URL globbing treat {} specially, so the request goes out malformed or not at all. Use curl -G --data-urlencode, curl -g, or build the query with URLSearchParams.

• Misspelling one field

  A single unknown name fails the entire call with Error 100 (Invalid Parameter) — "Tried accessing nonexisting field…" — not just that field. Keep field lists in constants and cover them in an integration test against a test number.

• Expanding everything

  Very wide or deep trees make slow responses, and the Graph API can reject them with an error asking you to reduce the amount of data requested. Expand only what the screen or job uses and page large edges with .limit().

• Treating expansion as pagination

  .limit(100) on an expanded edge still returns one page. If paging has an after cursor or a next link, there are more items — follow it rather than assuming the first page is complete.

• Keep each job's field list in one named constant so a code review shows exactly what it reads.
• Request health_status explicitly — the Health Status API is just this field, and it is only returned when you ask for it.
• Use the Graph API Explorer's field picker to discover valid field names before writing code.
• Log the fields string with each failed call; error 100 messages name the field that broke it.

What does the fields parameter do in the Graph API?

It limits the response to the properties you name. Without it, a node returns its default fields; with fields=a,b,c you get just those plus id, and braces let you expand edges to read related objects in the same call.

How do I get nested fields in one Graph API call?

Put the edge's fields in curly braces inside fields. On a WABA, fields=name,phone_numbers{display_phone_number,quality_rating} returns the account name and every number's display number and rating; add .limit(n) to the edge to cap items per page.

Does field expansion reduce rate-limit usage?

It reduces the number of calls, which is what Graph rate limits mainly count. One expanded request replaces several dependent ones, but some limits also weigh processing time, so a huge expansion is not free of cost — expand only what you use.

What is the difference between field expansion and pagination?

Field expansion chooses which properties each object returns; pagination chooses how many objects of an edge you get and how to fetch the next page. An expanded edge is still paginated, with paging cursors you follow for more items.