Media

Upload Media

Uploads a file to Meta’s resumable upload API and returns a media handle.

Two endpoints consume that handle: Create Template uses it as the header example for an IMAGE, VIDEO, or DOCUMENT header, and Update Business Profile uses it as profilePictureReference. Neither accepts raw file bytes or a public URL.

The endpoint runs both Meta steps in one call: it creates an upload session for the file length and content type, then uploads the bytes and reads back the handle. Content type is derived from the uploaded part, validated against the allowed list, and checked against the size limit for its media type — all before anything reaches Meta.

Limits. Image (image/jpeg, image/png) up to 5 MB, video (video/mp4) up to 16 MB, document (application/pdf) up to 100 MB. Anything else is rejected with 422.

A handle is single-use. It is consumed by the first request that references it and cannot be replayed. The same image used in two templates needs two uploads. Never cache or share handles.

This is the one Public API endpoint that is not JSON — the body is multipart/form-data.

POST

{app_id}

media

upload

Upload Media

curl --request POST \
  --url https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "data": {
    "handle": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value"
  },
  "isSuccess": true
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "errors": {
    "code": "WA_VAL_004",
    "group": "VALIDATION",
    "description": "File size 9437184 bytes exceeds maximum 5242880 bytes."
  },
  "isSuccess": false
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

Authorizations

Authorization

string

header

required

Secret key in Bearer sk_... format. Server-to-server only — never embed it in a browser or mobile client. The organization is resolved from the key, so organization_id is never passed explicitly.

Path Parameters

app_id

string

required

Application ID. Must belong to the organization resolved from your secret key, otherwise the request returns 404 with APPLICATION_004.

Example:

"app_7poyXj8GXuv76e"

Body

multipart/form-data

file

required

The file part. Its MIME type must be one of image/jpeg, image/png, video/mp4, application/pdf, and its size must stay within that media type's limit. Both the media type and the size are resolved from the uploaded part, so they are not sent separately.

Response

The media handle. It identifies the uploaded bytes on Meta's side; it is not a public URL and cannot be fetched directly.

data

object

Show child attributes

isSuccess

enum<boolean>

Available options:

true

Upload Media

curl --request POST \
  --url https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public-api.gateway.connexease.com/api/v1/wa/{app_id}/media/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "data": {
    "handle": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value"
  },
  "isSuccess": true
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "errors": {
    "code": "WA_VAL_004",
    "group": "VALIDATION",
    "description": "File size 9437184 bytes exceeds maximum 5242880 bytes."
  },
  "isSuccess": false
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

{
  "isSuccess": false,
  "errors": {
    "code": "META_075",
    "group": "VALIDATION",
    "description": "Template with 0000000000 not found in Meta.",
    "params": {},
    "fields": {}
  }
}

Getting Started

Sandbox Public API

Analytics

Application

Template

Media

Developers

Reference

Upload Media

Authorizations

Path Parameters

Body

Response