Resources
SDKs
Typed clients for Node.js, Python and Go, generated from the API's contract, with idempotency, retries, pagination and webhook verification built in.
The three SDKs are generated from the same OpenAPI contract as the API reference, so every endpoint is a typed method the day it ships. They follow the transport rules the API asks of every integration:
- Idempotency: every write carries an
Idempotency-Key— a fresh one per call unless you pass your own — and the same key on every retry of that call. - Retries: timeouts, network errors,
429,500,502,503,504and409 IDEMPOTENCY_KEY_IN_FLIGHTare retried with jittered exponential backoff that honoursRetry-After— only when repeating is safe. An error the API replayed from its idempotency store is final. - Errors: anything else raises an error carrying the API's
code,statusandrequestId— never your key, the body or the URL, so it is safe to log. - Pagination helpers that read every page, and webhook verification that checks the signature before parsing.
Node.js
@trovacast/sdk — ES modules, Node.js 22 or later, built on the platform fetch. One method per operation (createMessage, listContacts, …), named after the contract's operationId.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-confirmation' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "order_confirmation",
"language": "en"
},
"variables": {
"var1": "Aarav",
"var2": "#1001"
}
}'trovacast.withResponse.<method>(…)also returns the status, headers,requestId,idempotentReplayedand the key'srateLimit.trovacast.paginate('listMessages', …)iterates every item;pages(…)a page at a time.@trovacast/sdk/webhooksverifies and parses deliveries without the HTTP client:constructWebhookEvent({ payload, header, secrets }).- Options:
baseUrl,timeoutMs(30 s),maxRetries(2), backoff bounds,maxRetryAfterMs, a customfetchand auserAgentprefix.
Forward webhooks to your machine
trovacast listen --forward-to http://localhost:3000/webhooks forwards your project's webhook events to a local handler while you build it — no tunnel. Once the SDK is on npm it runs as npx @trovacast/sdk listen …; until then, run it from a package build (node node_modules/@trovacast/sdk/dist/cli.js listen …). It polls GET /v1/events (the key needs webhooks:manage and each event's read scope) and POSTs each new event's envelope, oldest first and once, re-signed with a local whsec_listen_… secret it prints at start: configure your handler's verifier with that secret while it runs behind the forwarder. --events, --since 10m and --interval narrow it. Events are recorded only for types an endpoint of the project subscribes to (a disabled endpoint counts).
Python
trovacast — Python 3.11 or later, on httpx, with a synchronous Trovacast client and an AsyncTrovacast with the same methods. Methods are the operationIds in snake_case (create_message, get_whatsapp_consent); path and query parameters are keyword arguments in snake_case, and bodies are dicts with the API's own camelCase field names, typed as TypedDicts.
import os
from trovacast import Trovacast, TrovacastApiError
with Trovacast(api_key=os.environ["TROVACAST_API_KEY"]) as client:
page = client.list_messages(contact_id="CONTACT_ID", limit=50)
for message in client.paginate("list_messages", contact_id="CONTACT_ID"):
print(message["id"], message["status"])
try:
client.get_contact(contact_id="CONTACT_ID")
except TrovacastApiError as error:
if error.is_not_found:
print("no such contact", error.request_id)
else:
raiseclient.with_response.<method>(…)also returns the status, headers,request_id,idempotent_replayedandrate_limit.trovacast.webhooks.construct_webhook_event(payload=…, header=…, secrets=[…])verifies and parses a delivery.- Errors are
TrovacastApiErrorwithcode,status,request_id,retryable,retry_afterandidempotent_replayed.
Go
github.com/trovakap/recalling-new/packages/trovacast-go (package trovacast) — Go 1.24 or later, standard library only. Methods are the operationIds in Go case (CreateMessage, GetWhatsAppConsent, ListSMSSenders); each takes a context.Context, the path parameters, a *<Method>Params struct for the query and a typed body, and returns the decoded answer. Every schema is a Go type with the API's own JSON field names: required fields are values, optional ones pointers (trovacast.Ptr), and an optional field the API also accepts as null is a trovacast.Nullable.
package main
import (
"context"
"errors"
"fmt"
"log"
"os"
trovacast "github.com/trovakap/recalling-new/packages/trovacast-go"
)
func main() {
ctx := context.Background()
client, err := trovacast.NewClient(os.Getenv("TROVACAST_API_KEY"))
if err != nil {
log.Fatal(err)
}
params := &trovacast.ListMessagesParams{ContactID: trovacast.Ptr("CONTACT_ID"), Limit: trovacast.Ptr(50.0)}
page, err := client.ListMessages(ctx, params)
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data), "messages on the first page")
it := client.ListMessagesIter(params)
for it.Next(ctx) {
fmt.Println(it.Item().ID, it.Item().Status)
}
if err := it.Err(); err != nil {
log.Fatal(err)
}
_, err = client.GetContact(ctx, "CONTACT_ID")
var apiErr *trovacast.APIError
switch {
case errors.As(err, &apiErr) && apiErr.IsNotFound():
fmt.Println("no such contact", apiErr.RequestID)
case err != nil:
log.Fatal(err)
}
}trovacast.WithResponseInfo(&info)also fills in the status, headers,RequestID,IdempotentReplayedand the key'sRateLimit.client.<Method>Iter(…)walks every page:for it.Next(ctx) { … it.Item() … }, orrange it.All(ctx).trovacast.VerifyWebhook(payload, header, secret, 0)verifies and parses a delivery; atrovacast.WebhookVerifierholds several secrets while you rotate.- Errors are
*trovacast.APIErrorwithCode,Status,RequestID,DocURL,Retryable,RetryAfterandIdempotentReplayed; a cancelled context returnsctx.Err()as it is.
Other languages
Generate a client from GET /v1/openapi.json with any OpenAPI 3 generator, or call the API directly — the PHP, Java and Go version of every request in these docs uses only each language's standard HTTP client (Guzzle for PHP). Whatever you use, send an Idempotency-Key on writes and back off on 429 and 5xx (Idempotency).