Trovacast

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, 504 and 409 IDEMPOTENCY_KEY_IN_FLIGHT are retried with jittered exponential backoff that honours Retry-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, status and requestId — 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.

Send a template
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, idempotentReplayed and the key's rateLimit.
  • trovacast.paginate('listMessages', …) iterates every item; pages(…) a page at a time.
  • @trovacast/sdk/webhooks verifies and parses deliveries without the HTTP client: constructWebhookEvent({ payload, header, secrets }).
  • Options: baseUrl, timeoutMs (30 s), maxRetries (2), backoff bounds, maxRetryAfterMs, a custom fetch and a userAgent prefix.

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.

Python: a page of messages, then every message (python)
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:
            raise
  • client.with_response.<method>(…) also returns the status, headers, request_id, idempotent_replayed and rate_limit.
  • trovacast.webhooks.construct_webhook_event(payload=…, header=…, secrets=[…]) verifies and parses a delivery.
  • Errors are TrovacastApiError with code, status, request_id, retryable, retry_after and idempotent_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.

Go: a page of messages, then every message (go)
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, IdempotentReplayed and the key's RateLimit.
  • client.<Method>Iter(…) walks every page: for it.Next(ctx) { … it.Item() … }, or range it.All(ctx).
  • trovacast.VerifyWebhook(payload, header, secret, 0) verifies and parses a delivery; a trovacast.WebhookVerifier holds several secrets while you rotate.
  • Errors are *trovacast.APIError with Code, Status, RequestID, DocURL, Retryable, RetryAfter and IdempotentReplayed; a cancelled context returns ctx.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).