API Reference v1

Tricknowtech API

The Tricknowtech REST API lets you integrate WhatsApp Business messaging and contact form submissions directly into your applications, workflows, and dashboards.

All API requests are made over HTTPS. Request and response bodies use JSON. Authenticated endpoints use a Bearer token in the Authorization header.

Base URL

https://api.tricknow.tech/api/v1

API Playground

Pick an endpoint, choose your WhatsApp account or form (auto-filled when you're logged in), paste an API key, and run a real request — right here.

Try it livePOST /public/wa/{uuid}/messages/text

Endpoint

WhatsApp account UUID

API key

Request body (JSON)

Requests run from your browser against the live API using the key you enter — nothing is stored. Log in to pick your account/form automatically.

Authentication

Authenticated endpoints require a Bearer API key in the Authorization header. Two types of keys are issued:

WhatsApp API Key

wak_live_…

Generate at:WhatsAppaccount pageAPI Keys tab

Go to dashboard

Form API Key

fak_live_…

Generate at:Formsselect a formAPI Keys

Go to dashboard

bash

# Every authenticated request must include this header
Authorization: Bearer wak_live_xxxxxxxxxxxx

# Example
curl https://api.tricknow.tech/api/v1/public/wa/42/templates \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx"

Rate Limits

All endpoints are rate-limited per IP address. When a limit is exceeded, the server returns HTTP 429 Too Many Requests. Retry after the number of seconds indicated in the Retry-After header.

Endpoint group	Limit
WhatsApp Public API (all endpoints)	60 req / min
Forms API — list submissions	60 req / min
Forms — public submit (POST /f/{uuid})	30 req / min

Errors

The API uses conventional HTTP status codes. Error responses include a JSON body with an error or message field.

Status	Meaning
200 OK	Request succeeded.
201 Created	Resource was created successfully.
202 Accepted	Message accepted for sending (async).
400 Bad Request	Malformed request or missing required fields.
401 Unauthorized	API key missing, invalid, or wrong prefix.
403 Forbidden	API key valid but expired, or key belongs to a different resource.
404 Not Found	Resource does not exist.
422 Unprocessable Entity	Validation failed or downstream API error.
429 Too Many Requests	Rate limit exceeded. Check Retry-After header.
500 Server Error	Unexpected server error. Contact support.

json

HTTP/1.1 401 Unauthorized

{
  "message": "Missing or invalid API key."
}

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The to field is required.",
  "errors": {
    "to": ["The to field is required."]
  }
}

Official SDKs

Zero-dependency TypeScript/JavaScript clients for each API below — typed requests and responses, no need to hand-roll fetch calls. Work in Node.js 18+, browsers, and edge runtimes.

@tricknowtech/email

Send transactional email — freeform or from a template.

npm install @tricknowtech/email

@tricknowtech/whatsapp

Send messages, manage contacts and templates.

npm install @tricknowtech/whatsapp

@tricknowtech/form

Submit from any website, read submissions from your server.

npm install @tricknowtech/form

Email example:

import { TricknowtechEmail } from '@tricknowtech/email'

const email = new TricknowtechEmail({ accountId: 'YOUR_ACCOUNT_UUID', apiKey: 'esk_...' })

await email.send({
  to: '[email protected]',
  subject: 'Your order has shipped',
  html: '<p>Hi Jane, your order is on its way.</p>',
})

WhatsApp API

WhatsApp Business API

Send and receive WhatsApp messages, manage contacts, and create message templates through a simple REST API backed by the Meta Cloud API.

All WhatsApp API endpoints are scoped to an account ID visible in your dashboard. Authentication uses a wak_ API key generated per account.

Let an AI agent do this for you

Copy a ready-made prompt for an AI coding assistant with terminal access to your server (Claude Code, Cursor, or similar) — it can carry out the steps below for you. Review what it plans to run before it executes anything.

Account base URL

https://api.tricknow.tech/api/v1/public/wa/{accountId}/…

POST/public/wa/{accountId}/messages/text

Send Text Message

Send a plain-text WhatsApp message to a phone number. The recipient must have an active 24-hour customer-service conversation window open (i.e. they messaged you first within the last 24 hours).

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
to	string	body	Yes	Recipient phone number with country code, no +. E.g. 919876543210
text	string	body	Yes	Message body text. Max 4096 characters.

Request

bash

curl -X POST https://api.tricknow.tech/api/v1/public/wa/42/messages/text \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "text": "Hello! Your order has been shipped."
  }'

Response

json

HTTP/1.1 202 Accepted

{
  "message_id": 101,
  "wamid": "wamid.HBgNOTE5ODc2NTQz...",
  "status": "sent"
}

POST/public/wa/{accountId}/messages/template

Send Template Message

Send a Meta-approved template message (HSM). Templates work outside the 24-hour window, making them ideal for transactional notifications, OTPs, and marketing broadcasts.

The template must have meta_status = "approved" before it can be sent.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
to	string	body	Yes	Recipient phone with country code
template_name	string	body	Yes	Exact name of an approved template
language	string	body	Yes	Language code, e.g. "en" or "en_US"
components	array	body	No	Variable substitutions for HEADER, BODY, and BUTTONS components

Request

bash

curl -X POST https://api.tricknow.tech/api/v1/public/wa/42/messages/template \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "template_name": "order_confirmation",
    "language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John Doe" },
          { "type": "text", "text": "ORD-12345" }
        ]
      }
    ]
  }'

Response

json

HTTP/1.1 202 Accepted

{
  "message_id": 102,
  "status": "queued"
}

GET/public/wa/{accountId}/contacts/{phone}

Get Contact

Look up a single contact by phone number. Returns the stored contact record or 404 if not found.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
accountId	integer	path	Yes	Your WhatsApp account ID
phone	string	path	Yes	Phone number with country code, no +

Request

bash

curl https://api.tricknow.tech/api/v1/public/wa/42/contacts/919876543210 \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx"

Response

json

HTTP/1.1 200 OK

{
  "id": 5,
  "account_id": 42,
  "phone": "919876543210",
  "name": "John Doe",
  "opted_out": false,
  "created_at": "2025-01-15T10:00:00.000000Z",
  "updated_at": "2025-05-20T14:22:00.000000Z"
}

POST/public/wa/{accountId}/contacts

Upsert Contact

Create a new contact or update an existing one identified by phone number. Returns 201 on creation, 200 on update.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
phone	string	body	Yes	Phone with country code (e.g. 919876543210)
name	string	body	No	Display name

Request

bash

curl -X POST https://api.tricknow.tech/api/v1/public/wa/42/contacts \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "919876543210", "name": "John Doe" }'

Response

json

HTTP/1.1 201 Created

{
  "id": 5,
  "account_id": 42,
  "phone": "919876543210",
  "name": "John Doe",
  "opted_out": false,
  "created_at": "2025-05-25T08:00:00.000000Z"
}

GET/public/wa/{accountId}/templates

List Templates

Return all message templates for the account. Optionally filter by approval status or search by name.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
status	string	query	No	Filter by Meta approval status: approved \| pending \| rejected
search	string	query	No	Keyword search against template name

Request

bash

curl "https://api.tricknow.tech/api/v1/public/wa/42/templates?status=approved" \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx"

Response

json

HTTP/1.1 200 OK

[
  {
    "id": 1,
    "name": "order_confirmation",
    "language": "en",
    "category": "UTILITY",
    "meta_status": "approved",
    "meta_template_id": "123456789",
    "components": [
      { "type": "BODY", "text": "Hi {{1}}, your order {{2}} is confirmed." }
    ],
    "created_at": "2025-03-01T09:00:00.000000Z"
  }
]

GET/public/wa/{accountId}/templates/{name}

Get Template

Retrieve a single template by its exact name.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
name	string	path	Yes	Exact template name (case-sensitive)

Request

bash

curl https://api.tricknow.tech/api/v1/public/wa/42/templates/order_confirmation \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx"

Response

json

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "order_confirmation",
  "language": "en",
  "category": "UTILITY",
  "meta_status": "approved",
  "components": [
    { "type": "BODY", "text": "Hi {{1}}, your order {{2}} is confirmed." }
  ]
}

POST/public/wa/{accountId}/templates

Create Template

Submit a new message template to Meta for approval. The template is saved locally with meta_status = "pending" and will be updated once Meta reviews it (typically minutes to 24 hours).

Template names must be lowercase with underscores only. Category must be MARKETING, UTILITY, or AUTHENTICATION.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
name	string	body	Yes	Unique template name. Lowercase, underscores only. E.g. order_shipped
language	string	body	Yes	BCP-47 language code. E.g. en, en_US, hi
category	string	body	Yes	MARKETING \| UTILITY \| AUTHENTICATION
components	array	body	Yes	At least one component of type HEADER, BODY, FOOTER, or BUTTONS

Request

bash

curl -X POST https://api.tricknow.tech/api/v1/public/wa/42/templates \
  -H "Authorization: Bearer wak_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} has been shipped! Track it at {{3}}."
      }
    ]
  }'

Response

json

HTTP/1.1 201 Created

{
  "id": 3,
  "name": "order_shipped",
  "language": "en",
  "category": "UTILITY",
  "meta_status": "pending",
  "meta_template_id": null,
  "created_at": "2025-05-25T10:00:00.000000Z"
}

Forms API

Contact Forms API

Submit entries to any Tricknowtech contact form and read back submissions programmatically. Forms are identified by a UUID (for submissions) or a numeric ID (for reading submissions via API key).

Let an AI agent do this for you

POST/f/{uuid}

Submit Form

Submit a form entry. This endpoint is public — no API key required. The UUID is your form's unique identifier, visible in the Forms dashboard. Field names must match the fields defined in your form.

The base path for this endpoint is /api/v1 (not /api/v1/public). Rate limited to 30 requests/minute per IP.

No authentication required

Parameters

Parameter	Type	In	Req?	Description
uuid	string (path)	path	Yes	Your form UUID, e.g. a1b2c3d4-...
(fields)	any	body	No	All form fields as defined in your form schema (name, email, message, etc.)

Request

bash

curl -X POST https://api.tricknow.tech/api/v1/f/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[email protected]",
    "message": "I have a question about my order."
  }'

Response

json

HTTP/1.1 200 OK

{
  "message": "Form submitted successfully."
}

GET/public/f/{formId}/submissions

List Submissions

Retrieve paginated form submissions, newest first. Returns 50 entries per page. Requires a Form API key (fak_…) scoped to the specific form.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
formId	integer	path	Yes	Numeric form ID (different from UUID)
page	integer	query	No	Page number, starting at 1 (default: 1)

Request

bash

curl "https://api.tricknow.tech/api/v1/public/f/7/submissions?page=1" \
  -H "Authorization: Bearer fak_live_xxxxxxxxxxxx"

Response

json

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": 201,
      "form_id": 7,
      "data": {
        "name": "Jane Smith",
        "email": "[email protected]",
        "message": "I have a question about my order."
      },
      "submitted_at": "2025-05-25T10:30:00.000000Z"
    }
  ],
  "current_page": 1,
  "per_page": 50,
  "last_page": 3,
  "total": 142
}

Email API

Email Sending API

Send transactional email through a simple REST API backed by Amazon SES. The platform is transactional-only — every send, freeform or templated, is verified transactional before it goes out.

Sends are scoped to an email account, identified by its UUID (not its numeric id) in the URL. Authentication uses an esk_ API key generated per account.

Let an AI agent do this for you

There are two ways to send:

Freeform

Pass html and/or textdirectly in the request. Content is classified live by an LLM on every send to confirm it's transactional — this adds latency to the request.

Template

Pass a template_id instead. Templates are classified once, up front, when created or edited — an approved template skips live classification entirely, so sends are faster and never blocked on classifier availability.

Every account can send immediately on the shared domain mail.tricknow.tech— no setup required. To send from your own domain instead, register it under the Email product's Domains tab; this creates DKIM records you add to your DNS, and the domain becomes usable once verification completes.

The send endpoint returns:

Status	Meaning
202 Accepted	Sent via SES. An EmailMessage row is created with status "sent".
401 Unauthorized	Bearer token missing, malformed (no esk_ prefix), or the key is not found/inactive.
402 Payment Required	No active Email Sending API subscription, monthly quota exceeded with no overage, or insufficient wallet balance.
403 Forbidden	API key has expired, or the account UUID in the path does not match the key’s account.
404 Not Found	template_id was given but no matching template exists on this account.
422 Unprocessable Entity	Validation failure; template not approved; neither html nor text given; recipient previously bounced/complained; or content was classified non-transactional.

Account base URL

https://api.tricknow.tech/api/v1/public/email/{accountUuid}/send

POST/public/email/{accountUuid}/send

Send Email

Send one transactional email, either from a pre-approved template or freeform content classified live by an LLM. Every send is verified transactional — the platform is transactional-only.

accountUuid is the EmailAccount UUID shown in your dashboard, not its numeric id. The API key must belong to that exact account, or the request is rejected.

Bearer token required

Parameters

Parameter	Type	In	Req?	Description
to	string (email)	body	Yes	Recipient address. Max 255 characters.
template_id	integer	body	No	If given, sends via an approved template on this account instead of freeform content.
variables	object<string,string>	body	No	Only used with template_id. Fills {{variable}} placeholders in the template; unmatched placeholders are left as-is.
subject	string	body	No	Required unless template_id is given (subject then comes from the template and this field is ignored). Max 255 characters.
html	string	body	No	HTML body. Max 200,000 characters. At least one of html/text is required for a freeform send.
text	string	body	No	Plain-text body. Max 100,000 characters.
from_name	string	body	No	Overrides the account's default from name for this send. Max 120 characters.

Request

bash

# Freeform — content is classified live before sending
curl -X POST https://api.tricknow.tech/api/v1/public/email/3f2c1a9e-4b7d-4e12-9c3a-1234567890ab/send \
  -H "Authorization: Bearer esk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your order has shipped",
    "html": "<p>Hi Jane, your order #1234 is on its way.</p>",
    "text": "Hi Jane, your order #1234 is on its way."
  }'

# Template — pre-approved, skips live classification
curl -X POST https://api.tricknow.tech/api/v1/public/email/3f2c1a9e-4b7d-4e12-9c3a-1234567890ab/send \
  -H "Authorization: Bearer esk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "template_id": 12,
    "variables": { "customer_name": "Jane", "order_id": "1234" }
  }'

Response

json

HTTP/1.1 202 Accepted

{
  "message_id": 501,
  "provider_message_id": "0100018f2a3b4c5d-11223344-5566-7788-99aa-bbccddeeff00-000000",
  "status": "sent"
}

Need help? Contact support · Sign in to dashboard