Upload WhatsApp Template Media Files with OAuth 2.0

You can use the WhatsApp Template Management API to upload files when your template components need a media handle for an image, video, or document header. You can use this API version if you authenticate requests with an Insider One API key.

Field naming rule
The token generation request uses snake_case fields, such as client_id and client_secret. Template CRUD request bodies use camelCase fields, such as name, language, category, and components.

Endpoint and Headers

POST https://gw.useinsider.com/api/wa/v2/templates/file-upload

Headers

Header	Sample Value	Description
Authorization: Bearer your-oauth2-token	1a2b3c4d5e6f	This key is required to authorize your request. Refer to Generate OAuth 2.0 Credentials for WhatsApp Template Management to generate your credentials.
Content-Type	application/json	This header specifies the media type of the resource.

Body Parameters

Column	Data Type	Required	Description
name	String	Yes	The template name to create.
language	String	Yes	The template locale, such as `en_US`.
category	String	Yes	The Meta template category.
components	Array[object]	Yes	At least one component is required.

Sample Request

curl --location 'https://gw.useinsider.com/api/wa/v2/templates/file-upload' \
--header 'Authorization: Bearer your-oauth2-token' \
--form 'file=@"/path/to/header-image.png"'

Sample Response

A successful request returns the following JSON response.

{
  "id": "4::aW1hZ2UvcG5n:ARbExampleMediaHandle"
}

Sample Error Responses

Most template endpoint failures return a JSON body with a message field. Creating validation failures can also include an error field. OAuth token and scope failures may be returned by the Gateway before the request reaches the template service.

401 Unauthorized: Invalid OAuth Client Credentials

You will receive this error if the token request contains an invalid client_id or client_secret,

{
  "message": "invalid client credentials"
}

401 Unauthorized: Missing or Invalid Bearer Token

You will receive this error if the token is missing, expired, or malformed.

{
  "message": "unauthorized"
}

403 Forbidden: Missing Required Scope

You will receive this error if the token does not include the required scope for the operation.

{
  "message": "forbidden"
}

400 Bad Request: Invalid JSON Body

You will receive this error if the request body cannot be decoded.

{
  "message": "failed to decode request"
}

400 Bad Request: Missing Required Fields

You will receive this error if a required field, such as name, language, or components is missing.

{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"
}

400 Bad Request: Empty Components Array

You will receive this error if components is provided but empty.

{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Components' Error:Field validation for 'Components' failed on the 'min' tag"
}

Invalid List Query Parameters

You will receive this error if the “List” endpoint validation runs before querying templates.

{ "message": "page must be a positive integer" }
{ "message": "per_page must be between 1 and 100" }
{ "message": "sort must be in column|direction format" }
{ "message": "sort column is invalid" }
{ "message": "sort direction is invalid" }

400 Bad Request: Invalid Template ID in Path

You will receive this error if the :id path parameter is not numeric.

{
  "message": "template id is invalid"
}

404 Not Found: Template Not Found

You will receive this error if the template does not exist for the authenticated partner, the detail and delete endpoints return.

{
  "message": "template not found"
}

422 Unprocessable Entity: Router Domain Missing for URL Buttons

You will receive this error if you create a template with URL buttons, but you have no active WhatsApp router domain.

{
  "message": "active whatsapp router domain not found"
}

Meta Rejects the Template Payload

You will receive this error if Meta validation errors are exposed as readable messages. Unsupported button combinations are a common example.

{
  "message": "Invalid parameter - buttons: quick reply and url combination is not supported"
}

400 Bad Request: Upload Request Without a File

You will receive this error if the multipart upload request does not contain a file field.

{
  "message": "file is required"
}

429 Too Many Requests: Upload Rate Limit Exceeded

You will receive this error if you exceed the upload quota.

{
  "message": "upload rate limit exceeded"
}

Media Upload Fails Upstream

If Meta rejects the uploaded file type or upload session, the API returns the upstream message.

{
  "message": "Unsupported post request. Object with ID 'upload-session-id' does not exist"
}

Unexpected Upstream or Local Failure

In less common cases, the API can return internal decoding or persistence errors.

{ "message": "failed to decode template creation response" }
{ "message": "template created in Meta but could not be persisted locally" }