> For the complete documentation index, see [llms.txt](https://docs.zenfinder.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenfinder.ai/reference/models.md).

# Models

## The Error object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"Error":{"type":"object","description":"Graph/WhatsApp-Cloud-API-compatible error envelope. Numeric `code`\nvalues are reused verbatim from the WhatsApp Cloud API:\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| 0 | 401 | AuthException |\n| 3 | 403 | Capability or permissions issue |\n| 10 | 403 | Permission denied |\n| 100 | 400 | Invalid parameter |\n| 190 | 401 | Access token invalid or expired |\n| 200 | 403 | Permission denied (missing scope / not authorised for this resource) |\n| 130429 | 429 | Rate limit hit |\n| 131000 | 500 | Something went wrong |\n| 131008 | 400 | Required parameter is missing |\n| 131009 | 400 | Parameter value is not valid |\n| 131016 | 503 | Service unavailable |\n| 131021 | 400 | Recipient cannot be sender |\n| 131026 | 400 | Message undeliverable |\n| 131037 | 403 | Display name not approved |\n| 131042 | 402 | Business eligibility payment issue (insufficient wallet balance) |\n| 131047 | 400 | Re-engagement message (service window closed — send a template) |\n| 131048 | 400 | Spam rate limit hit |\n| 131049 | 400 | Per-user marketing message limit reached |\n| 131050 | 400 | User stopped marketing messages (opted out) |\n| 131051 | 400 | Unsupported message type |\n| 131052 | 400 | Media download error |\n| 131053 | 400 | Media upload error |\n| 132000 | 400 | Template parameter count mismatch |\n| 132001 | 400 | Template does not exist / not approved |\n| 132005 | 400 | Template hydrated text too long |\n| 132007 | 400 | Template format character policy violated |\n| 132012 | 400 | Template parameter format mismatch |\n| 132015 | 400 | Template is paused |\n| 132016 | 400 | Template is disabled |\n| 133010 | 400 | Sender not registered |\n","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"integer"},"error_subcode":{"type":"integer","nullable":true},"error_data":{"type":"object","properties":{"messaging_product":{"type":"string"},"details":{"type":"string"}}},"zen_trace_id":{"type":"string"}}}}}}}}
```

## The TextMessage object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TextMessage":{"type":"object","required":["to","type","text"],"properties":{"messaging_product":{"type":"string","enum":["zenfinder","whatsapp"]},"to":{"type":"string","description":"Recipient in E.164 (leading `+` and country code required)"},"type":{"type":"string","enum":["text"]},"text":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":4096},"preview_url":{"type":"boolean","default":false}}},"context":{"type":"object","description":"Reply threading.","properties":{"message_id":{"type":"string"}}}}}}}}
```

## The MediaMessage object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"MediaMessage":{"type":"object","required":["to","type"],"properties":{"messaging_product":{"type":"string","enum":["zenfinder","whatsapp"]},"to":{"type":"string"},"type":{"type":"string","enum":["image","document"]},"image":{"$ref":"#/components/schemas/MediaObject"},"document":{"$ref":"#/components/schemas/MediaObject"},"context":{"type":"object","properties":{"message_id":{"type":"string"}}}}},"MediaObject":{"type":"object","description":"Exactly one of `id` (from a prior media upload) or `link` (a public URL) is required.","properties":{"id":{"type":"string","description":"MEDIA_ID from a prior upload."},"link":{"type":"string","format":"uri"},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","description":"document type only."}}}}}}
```

## The MediaObject object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"MediaObject":{"type":"object","description":"Exactly one of `id` (from a prior media upload) or `link` (a public URL) is required.","properties":{"id":{"type":"string","description":"MEDIA_ID from a prior upload."},"link":{"type":"string","format":"uri"},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","description":"document type only."}}}}}}
```

## The LocationMessage object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"LocationMessage":{"type":"object","required":["to","type","location"],"properties":{"messaging_product":{"type":"string","enum":["zenfinder","whatsapp"]},"to":{"type":"string"},"type":{"type":"string","enum":["location"]},"location":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"name":{"type":"string"},"address":{"type":"string"}}}}}}}}
```

## The InteractiveMessage object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"InteractiveMessage":{"type":"object","required":["to","type","interactive"],"properties":{"messaging_product":{"type":"string","enum":["zenfinder","whatsapp"]},"to":{"type":"string"},"type":{"type":"string","enum":["interactive"]},"interactive":{"type":"object","required":["type","body"],"properties":{"type":{"type":"string","enum":["button","list","cta_url","location_request","address_message","carousel"]},"header":{"type":"object","properties":{"text":{"type":"string","maxLength":60}}},"body":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":1024}}},"footer":{"type":"object","properties":{"text":{"type":"string","maxLength":60}}},"action":{"type":"object","description":"Shape depends on `interactive.type`:\n- `button`: `{ buttons: [{ type:\"reply\", reply:{ id, title (<=20 chars) } }] }` (1–3 buttons)\n- `list`: `{ button: \"<=20 chars\", sections: [{ title?, rows: [{ id, title (<=24), description? (<=72) }] }] }` (1–10 sections, <=10 rows total)\n- `cta_url`: `{ parameters: { display_text: \"<=60 chars\", url: \"https://...\" } }`\n- `location_request`: no extra fields — body + a send-location button.\n- `address_message`: `{ button?: \"<=20 chars\", country?: \"2-letter ISO code\" }`\n- `carousel`: `{ cards: [{ image:{ link }, body:{ text (<=160) }, action:{ buttons:[{type:\"reply\",reply:{id,title}}] } }] }` (1–10 cards, 1–2 buttons each, same button config across all cards)\n"}}}}}}}}
```

## The TemplateMessage object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TemplateMessage":{"type":"object","required":["to","type","template"],"properties":{"to":{"type":"string"},"type":{"type":"string","enum":["template"]},"template":{"type":"object","required":["name","language"],"properties":{"name":{"type":"string"},"language":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}},"components":{"type":"array","description":"Parameter values for the approved template's BODY (and TEXT HEADER, if any). Only `type:\"text\"` parameters are supported.","items":{"type":"object","properties":{"type":{"type":"string","enum":["body","header"]},"parameters":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}}}}}}}}}}}}}}
```

## The ReadReceipt object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"ReadReceipt":{"type":"object","required":["status","message_id"],"properties":{"status":{"type":"string","enum":["read"]},"message_id":{"type":"string"}}}}}}
```

## The TypingIndicator object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TypingIndicator":{"type":"object","required":["typing_indicator"],"properties":{"typing_indicator":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text"]}}},"message_id":{"type":"string"}}}}}}
```

## The MessageAcceptedResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"MessageAcceptedResponse":{"type":"object","properties":{"messaging_product":{"type":"string"},"contacts":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"zen_id":{"type":"string"}}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message_status":{"type":"string","enum":["accepted"]}}}}}}}}}
```

## The DryRunPriceResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"DryRunPriceResponse":{"type":"object","description":"Returned only for `type:\"template\"` sends with `?dry_run=true` — no message is sent or charged.","properties":{"messaging_product":{"type":"string"},"pricing":{"type":"object","properties":{"billable":{"type":"boolean"},"amount_minor":{"type":"integer","description":"Price in the ZBA currency's minor units (e.g. kobo, cents)."},"currency":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"reason":{"type":"string","enum":["service","free_entry_point","utility_in_window","no_rate","charged"]}}}}}}}}
```

## The SimpleSuccessResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"SimpleSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"messaging_product":{"type":"string"}}}}}}
```

## The MediaGetResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"MediaGetResponse":{"type":"object","properties":{"messaging_product":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri","description":"Signed download URL, valid for 5 minutes."},"mime_type":{"type":"string"},"sha256":{"type":"string"},"file_size":{"type":"integer"}}}}}}
```

## The TemplateComponent object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TemplateComponent":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["HEADER","BODY","FOOTER","BUTTONS"]},"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"HEADER only; defaults to TEXT."},"text":{"type":"string","description":"BODY (<=1024 chars, required), HEADER TEXT (<=60), or FOOTER (<=60, no parameters allowed)."},"buttons":{"type":"array","description":"BUTTONS component only. Max 10 total; same-type buttons must be consecutive.","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","OTP","FLOW"]},"text":{"type":"string","maxLength":25},"url":{"type":"string","format":"uri","description":"URL buttons must use https. Max 2 URL buttons."}}}}}}}}}
```

## The TemplateCreate object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TemplateCreate":{"type":"object","required":["name","language","category","components"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$","description":"Lowercase letters, digits, underscore only."},"language":{"type":"string","description":"e.g. 'en' or 'en_US'."},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"parameter_format":{"type":"string","enum":["POSITIONAL","NAMED"],"default":"POSITIONAL"},"components":{"type":"array","description":"Exactly one BODY (required); at most one each of HEADER, FOOTER,\nBUTTONS. AUTHENTICATION templates must include exactly one OTP\nbutton and cannot contain URLs, media headers, or emoji.\nCOPY_CODE buttons are MARKETING-only. Content referencing a\nregulated vertical (lending, gambling, forex/crypto, health\nclaims) is hard-rejected before any LLM review.\n","items":{"$ref":"#/components/schemas/TemplateComponent"}}}},"TemplateComponent":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["HEADER","BODY","FOOTER","BUTTONS"]},"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"HEADER only; defaults to TEXT."},"text":{"type":"string","description":"BODY (<=1024 chars, required), HEADER TEXT (<=60), or FOOTER (<=60, no parameters allowed)."},"buttons":{"type":"array","description":"BUTTONS component only. Max 10 total; same-type buttons must be consecutive.","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","OTP","FLOW"]},"text":{"type":"string","maxLength":25},"url":{"type":"string","format":"uri","description":"URL buttons must use https. Max 2 URL buttons."}}}}}}}}}
```

## The TemplateSummary object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TemplateSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"correct_category":{"type":"string","nullable":true,"description":"Set if the classifier recategorised the template from its declared category."},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"]},"quality_score":{"type":"string"},"rejection_reason":{"type":"string","nullable":true}}}}}}
```

## The Template object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"Template":{"allOf":[{"$ref":"#/components/schemas/TemplateSummary"},{"type":"object","properties":{"zba_id":{"type":"string"},"parameter_format":{"type":"string","enum":["POSITIONAL","NAMED"]},"components":{"type":"array","items":{"$ref":"#/components/schemas/TemplateComponent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}]},"TemplateSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"correct_category":{"type":"string","nullable":true,"description":"Set if the classifier recategorised the template from its declared category."},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"]},"quality_score":{"type":"string"},"rejection_reason":{"type":"string","nullable":true}}},"TemplateComponent":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["HEADER","BODY","FOOTER","BUTTONS"]},"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"HEADER only; defaults to TEXT."},"text":{"type":"string","description":"BODY (<=1024 chars, required), HEADER TEXT (<=60), or FOOTER (<=60, no parameters allowed)."},"buttons":{"type":"array","description":"BUTTONS component only. Max 10 total; same-type buttons must be consecutive.","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","OTP","FLOW"]},"text":{"type":"string","maxLength":25},"url":{"type":"string","format":"uri","description":"URL buttons must use https. Max 2 URL buttons."}}}}}}}}}
```

## The BlockUsersRequest object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"BlockUsersRequest":{"type":"object","required":["block_users"],"properties":{"block_users":{"type":"array","minItems":1,"items":{"type":"object","required":["user"],"properties":{"user":{"type":"string","description":"Recipient phone number (E.164 or digits-only zen_id)."}}}}}}}}}
```

## The BlockUsersResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"BlockUsersResponse":{"type":"object","properties":{"block_users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string","description":"The zen_id that was (un)blocked."},"success":{"type":"boolean"}}}}}}}}}
```

## The AnalyticsResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"AnalyticsResponse":{"type":"object","properties":{"analytics":{"type":"object","properties":{"granularity":{"type":"string","enum":["DAY","MONTH"]},"data_points":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"sender_id":{"type":"string"},"country":{"type":"string"},"type":{"type":"string"},"sent":{"type":"integer"},"delivered":{"type":"integer"}}}}}}}}}}}
```

## The PricingAnalyticsResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"PricingAnalyticsResponse":{"type":"object","properties":{"pricing_analytics":{"type":"object","properties":{"data_points":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"country":{"type":"string"},"currency":{"type":"string"},"cost_minor":{"type":"integer"},"message_count":{"type":"integer"}}}}}}}}}}}
```

## The TemplateAnalyticsResponse object

```json
{"openapi":"3.0.3","info":{"title":"ZenFinder Business API","version":"1.0"},"components":{"schemas":{"TemplateAnalyticsResponse":{"type":"object","properties":{"template_analytics":{"type":"object","properties":{"data_points":{"type":"array","items":{"type":"object","properties":{"template_id":{"type":"string"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"read":{"type":"integer"},"clicked":{"type":"integer","nullable":true,"description":"Always null — button/CTA click tracking isn't implemented yet."}}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zenfinder.ai/reference/models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.