Skip to content
DashboardGet API key

Submit a template to WhatsApp

View .md
POST

Submit a draft template to Meta for approval, naming the WhatsApp number by its address (from).

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • templateIdstringrequired

Body

application/json

  • fromstringrequired

    The WhatsApp number whose Business Account receives the template: an address with a whatsapp entry in GET /v2/channels.

  • categorystring

    WhatsApp template category.

    One ofUTILITYMARKETINGAUTHENTICATION

Responses

202Submitted; status becomes `pending`.
  • idstringrequired
  • namestringrequired

    Template name. For WhatsApp, must match the approved template name in Meta.

  • languagestringrequired

    Language code.

  • bodystringrequired

    Default template body with variables: positional ({{1}}, {{2}}) or named ({{customer_name}}, {{contact.first_name}}). Templates created in Zavu are submitted to Meta as positional; templates imported from a WhatsApp Business Account keep their original format (named or positional). Used when no channel-specific body is set.

  • smsBodystring

    Channel-specific body for SMS messages. Falls back to body if not set.

  • telegramBodystring

    Channel-specific body for Telegram messages. Falls back to body if not set.

  • instagramBodystring

    Channel-specific body for Instagram messages. Falls back to body if not set.

  • categorystringrequired

    The category the template is billed under. For a template linked to WhatsApp this is the category Meta currently assigns, not the one it was submitted with: Meta can recategorize a template at approval or at any point afterwards, and that changes what the message costs.

    A recategorization reaches this field through the template.status_changed webhook, which carries data.category, and through POST /v1/templates/sync, which reconciles it against Meta. Read one of those rather than assuming the category you sent is the one in force.

    For a template that was never submitted to WhatsApp, this is the category stored locally, defaulting to UTILITY.

    One ofUTILITYMARKETINGAUTHENTICATION
  • statusstring
    One ofdraftpendingapprovedrejected
    Defaultdraft
  • variablesstring[]

    List of variable names for documentation.

  • headerTypestring

    Type of header (text, image, video, document).

  • headerContentstring

    Header content (text or media URL).

  • footerstring

    Footer text for the template.

  • buttonsobject[]

    Template buttons.

    8 properties
    • typestring
      One ofquick_replyurlphoneotprequest_contact_info
    • textstring
    • urlstring
    • examplestring

      Sample value used to substitute {{1}} in the URL when submitting the template to Meta for review. Only present for dynamic URL buttons.

    • phoneNumberstring
    • otpTypestring

      OTP button type. Required when type is 'otp'.

      One ofCOPY_CODEONE_TAP
    • packageNamestring

      Android package name. Required for ONE_TAP buttons.

    • signatureHashstring

      Android app signature hash. Required for ONE_TAP buttons.

  • addSecurityRecommendationboolean

    Add 'Do not share this code' disclaimer. Only for AUTHENTICATION templates.

  • codeExpirationMinutesinteger

    Code expiration time in minutes. Only for AUTHENTICATION templates.

    Limitsmin 1 · max 90
  • whatsappobject

    WhatsApp-specific template information.

    3 properties
    • templateNamestring

      WhatsApp template name.

    • namespacestring

      WhatsApp Business Account namespace.

    • statusstring

      WhatsApp approval status.

  • createdAtstring<date-time>
  • updatedAtstring<date-time>
400Not a draft, or `no_whatsapp`: the `from` address exists but has no WhatsApp Business Account (`details.types` lists what it has).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
404Template not found, or no channel of this project has the `from` address.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
409`ambiguous_from`: two of your senders have a `whatsapp` entry with this address.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring