WWagent Developers
API v1 · Production

Build with Wagent

Read conversations and contacts, control human takeover, send safe idempotent replies, and react to real-time Wagent events.

HTTPS only
Encrypted in transit
Tenant isolated
Every resource is account-scoped
Retry safe
Idempotent message actions

Authentication

Create an API key in Dashboard → Developer API. The secret is shown once. Send it as a Bearer token and request only the scopes your automation needs.

curl https://www.hirewagent.com/api/v1/me \
  -H "Authorization: Bearer wagent_live_..." \
  -H "Accept: application/json"
Never expose an API key in browser code, public repositories, chat transcripts, or client-side automation fields.

Endpoints

Base URL: https://www.hirewagent.com/api/v1

GET/me

Verify the API connection and inspect its scopes.

—
GET/agents

List setters in the connected Wagent account.

agents:read
GET/conversations

List conversations with cursor pagination and filters.

conversations:read
GET/conversations/{id}

Retrieve one conversation.

conversations:read
GET/conversations/{id}/messages

List messages in a conversation.

conversations:read
POST/conversations/{id}/messages

Send a reply and place the chat in human takeover.

conversations:write
POST/conversations/{id}/pause

Pause AI and request human takeover.

conversations:write
POST/conversations/{id}/resume

Resume AI replies for a conversation.

conversations:write
GET/contacts

List contacts or find one by exact email or phone.

contacts:read
GET/contacts/{id}

Retrieve one contact.

contacts:read
PATCH/contacts/{id}

Update contact fields, tags, or metadata.

contacts:write
GET/bookings

List Calendly bookings.

bookings:read
GET/webhooks

List registered webhook endpoints.

webhooks:read
POST/webhooks

Register a signed webhook endpoint.

webhooks:write
DELETE/webhooks/{id}

Delete a webhook endpoint.

webhooks:write

Pagination

Collection endpoints use opaque cursor pagination. Pass the returned next_cursor unchanged. Page size defaults to 25 and is capped at 100.

{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJ0aW1lc3RhbXAiOi4uLn0"
  }
}

Safe message delivery

Every outbound message requires a unique Idempotency-Key. Retrying the same request with the same key returns the original result instead of sending a duplicate. Reusing it for different content returns HTTP 409.

curl -X POST \
  https://www.hirewagent.com/api/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer wagent_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2ed28d6e-78bd-4c1f-a18b-5d931ee77028" \
  -d '{"content":"I can help with that."}'

Signed webhooks

Register a public HTTPS endpoint. Wagent returns its signing secret once, signs the exact body with HMAC-SHA256, retries temporary failures with exponential backoff, and disables endpoints that return HTTP 410.

message.received

A new inbound message was received.

message.sent

Wagent or a human sent a message.

conversation.handoff_requested

A conversation needs human attention.

contact.created

A new contact entered Wagent.

booking.created

A Calendly booking was created.

booking.canceled

A Calendly booking was canceled.

Delivery headers

  • Wagent-Event — event name
  • Wagent-Delivery — unique delivery identifier
  • Wagent-Timestamp — Unix timestamp
  • Wagent-Signature — t=TIMESTAMP,v1=HEX_DIGEST

Node.js verification

import crypto from "node:crypto";

const timestamp = req.headers["wagent-timestamp"];
const supplied = req.headers["wagent-signature"].split("v1=")[1];
const expected = crypto
  .createHmac("sha256", process.env.WAGENT_WEBHOOK_SECRET)
  .update(timestamp + "." + rawRequestBody)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(supplied), Buffer.from(expected))) {
  throw new Error("Invalid Wagent signature");
}

Errors and rate limits

Errors are JSON and include a stable machine-readable code plus a request ID. Each key may make 120 requests per minute. Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

400

Invalid request, JSON, cursor, or missing idempotency key.

401

API key is missing, malformed, expired, or revoked.

403

The key lacks a required scope or the account is inactive.

404

The resource does not exist in the authenticated account.

409

Idempotency or resource conflict.

422

A supplied field failed validation.

429

The API key exceeded its per-minute rate limit.

500/503

A temporary internal or dependency error occurred.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This request requires: contacts:write.",
    "request_id": "31fe2bf4-..."
  }
}

Automation platforms

Use an HTTP action for API calls and a webhook trigger for instant events. The same contract powers Zapier, Make, HighLevel, n8n, and Pipedream.

View integration guides

Support and policies

Include the response header X-Request-Id when reporting an API problem.

Developer supportPrivacy PolicyTerms of Servicesupport@hirewagent.com