Pingy API documentation

01How it works

Pingy is a RESTful API over HTTPS. Your server sends a JSON request with an API key, and Pingy delivers the message through the official WhatsApp Business Platform from the shared Pingy number or from your own connected number. Calls over plain HTTP and calls without a key fail.

Every message uses a template that Meta has approved. You write the template in your dashboard, Pingy submits it to Meta for review, and once it is approved you use its template_id in your requests. Your request chooses the template; your dashboard chooses the sender number, so the same request works with the shared number and with your own number.

All endpoints use POST with Content-Type: application/json. A 202 response with the state accepted means Pingy accepted the request. Delivery is reported later through the status endpoint, and your balance is charged only for delivered messages.

02Before your first request

1. Create your account and workspace. Your workspace_id is shown in the dashboard under Integrations.
2. Write a template and wait for Meta's approval. Copy its template_id from the Templates page once it is approved for the number you use.
3. Create an API key under Integrations. Start with a Sandbox key to test, then create a Live key. Give each key only the scopes the integration needs. The key is shown once; store it on your server.
4. Send your first request to the Sandbox base URL, then switch the base URL and the key to Live. The base URL for each environment is shown in your dashboard.

The examples below read the base URL and the key from the environment variables PINGY_API_BASE_URL and PINGY_SECRET_KEY. Replace the placeholder IDs and sample values with your own.

03Authentication and API keys

Send your key in the Authorization header as a Bearer token. Every request also needs a JSON content type:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Keys start with ak1_ and carry many privileges. Requests are server to server: browser cookies and requests coming from a web page are rejected, so never embed a key in a mobile app, in front-end code or in source control. Keep it in your server's secrets store or environment variables.

A Live key is rejected by the Sandbox, and a Sandbox key is rejected by Live. Each key carries the scopes you chose when you created it:

Create a separate key for each integration and give it only the scopes it needs. Revoking a key stops its future requests at once; it does not retract a message that was already accepted. Renaming a key changes its label only. All Live keys of a workspace share the same balance.

04Send a message

POST /customer/v1/send/service sends a utility or marketing message. The approved template decides the category; the request format is the same for both.

Templates with media or special layouts take extra optional fields: header_values, media_url, media_type, document_filename, location, carousel_values, commerce_values and flow_data_json. Include only the fields your approved template needs. Unknown fields, duplicate fields and null values are rejected.

curl --request POST "$PINGY_API_BASE_URL/customer/v1/send/service" \
  --header "Authorization: Bearer $PINGY_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "recipient": "+12025550199",
  "idempotency_key": "order-1048",
  "variables": [
    "Maya",
    "AC-1048"
  ]
}'

05Send a verification code

A verification code takes two calls. POST /customer/v1/otp/request generates the code on the server and sends it with an approved Authentication template. POST /customer/v1/otp/verify checks the code your customer typed. The code itself is never returned to you.

Request a code

curl --request POST "$PINGY_API_BASE_URL/customer/v1/otp/request" \
  --header "Authorization: Bearer $PINGY_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "template_id": "YOUR_AUTHENTICATION_TEMPLATE_ID",
  "recipient": "+12025550199",
  "idempotency_key": "sign-in-7f3a",
  "purpose": "sign_in",
  "transaction": "c2lnbl9pbg"
}'

Verify the code

When the customer enters the code, call verify with the same recipient, purpose and transaction:

curl --request POST "$PINGY_API_BASE_URL/customer/v1/otp/verify" \
  --header "Authorization: Bearer $PINGY_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "verification_id": "VERIFICATION_ID_FROM_REQUEST",
  "recipient": "+12025550199",
  "purpose": "sign_in",
  "transaction": "c2lnbl9pbg",
  "code": "CODE_ENTERED_BY_CUSTOMER"
}'

A code works once. Its expiry and the number of allowed guesses come from the verification policy of your workspace. verified is false for a wrong, expired or already-used code. If the customer needs a new code, start a new request with a new idempotency_key. Verification codes must be enabled for your workspace; the dashboard shows whether they are.

06Check message status

POST /customer/v1/messages/status returns the current state of a message. Use the same key that created it, with the messages.read scope, or otp.read for a verification code. Reading the state sends nothing.

curl --request POST "$PINGY_API_BASE_URL/customer/v1/messages/status" \
  --header "Authorization: Bearer $PINGY_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "attempt_id": "ATTEMPT_ID_FROM_RESPONSE"
}'

Cancel a queued message

POST /customer/v1/messages/cancel takes the same workspace_id and attempt_id and cancels a message that is still queued. A message already handed to WhatsApp cannot be cancelled. Cancelling a verification-code message also cancels its code.

curl --request POST "$PINGY_API_BASE_URL/customer/v1/messages/cancel" \
  --header "Authorization: Bearer $PINGY_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "attempt_id": "ATTEMPT_ID_FROM_RESPONSE"
}'

You can also follow every message in Message logs in your dashboard.

07Retries and idempotency

Every send and verification request carries an idempotency_key that you generate. If the connection drops before you receive a response, send exactly the same request again with the same key: Pingy returns the original attempt with replayed: true and does not send a second message. Sending the same key with different data returns 409 conflict. Do not create a new key only because a request timed out.

Idempotency is tied to the workspace and to the exact API key. Rotating the key in the middle of a retry can create a new message.

08Sandbox (test environment)

The Sandbox has its own base URL and works with Sandbox keys. It accepts the same endpoints, fields and responses as Live, but sends nothing to WhatsApp and never touches your balance. Build and test your integration against it, then switch the base URL and the key to Live.

No number is contacted. The Sandbox verification code is always 000000; it expires after 5 minutes, allows 5 guesses and works once.

Use your own workspace template IDs so your code stays the same in Live. If you have no approved template yet, the Sandbox accepts three fixture templates at revision 1: wt1_99999999999999999999999999999991 (utility, two body values), wt1_99999999999999999999999999999992 (marketing, two body values) and wt1_99999999999999999999999999999993 (authentication). Fixture IDs work only in the Sandbox.

Sandbox records expire after 24 hours. The Sandbox checks the shape of your request and the template values; it does not check media URLs, Meta approval or the connection of your number. Have those ready before you go Live. Your dashboard also includes a Playground that runs these requests from the browser with a Sandbox key.

09Errors and limits

A rejected request returns an HTTP error code and a JSON body with one field, status:

{ "status": "invalid" }

Limits: a send request body is at most 64 KiB and a verification request 8 KiB. Query strings, unsupported content types, unknown fields, duplicate JSON keys and null values are rejected.