AI Coding Assistant Skills

This is a self-contained “skill” file for AI coding assistants that support the emerging SKILL.md convention (Claude Code being the primary one today). Drop it into your assistant’s skills folder and it’ll have working knowledge of Wetel’s API shape, auth model, and common gotchas — without you having to paste this whole site into every conversation.

No install step, no npm package, no SDK required — this is a plain markdown file.

Install

Save the content below as wetel-integration/SKILL.md in your skills directory:

• Claude Code, personal (all projects): ~/.claude/skills/wetel-integration/SKILL.md
• Claude Code, this project only: .claude/skills/wetel-integration/SKILL.md at your repo root

Then just ask your assistant to build something against Wetel — it’ll pick up the skill automatically when the request matches.

The skill

---
name: wetel-integration
description: Use when building an integration with Wetel, an AI agent platform — creating/configuring agents, writing workflow graphs, calling the GraphQL API, or debugging a Wetel integration. Covers auth, the core session flow, the workflow node model, and common mistakes.
---

# Building on Wetel

Wetel is a GraphQL-only AI agent platform. An **Agent** has a persona and is driven by a **Workflow** (a graph of nodes/edges). Integrators talk to it over one endpoint: `https://api.wetel.dev/graphql`.

Full reference: https://wetel.dev/docs/ — treat this skill as a fast-start summary, not the complete spec. Check the live docs for anything not covered here, especially exact field names before writing real code (the API reference there is generated from the real schema, not hand-maintained prose).

## Every single request needs this header

```
x-huat-platform: customer
```

Missing it produces an error that looks unrelated to auth ("Platform is not specified!"). This is the single most common first-integration mistake — check it first if anything fails mysteriously.

## Auth — three credential types, don't mix them up

| Credential                    | Get it via                           | Unlocks                                                    |
| ----------------------------- | ------------------------------------ | ---------------------------------------------------------- |
| JWT                           | `login` mutation                     | Full dashboard/builder access (agents, workflows, admin)   |
| API key                       | `generateApiKey` (needs a JWT first) | `sdkStart` only                                            |
| Session token (`avatarToken`) | Returned by `sdkStart`               | `sdkSendMessage`, `sdkEndSession`, the events subscription |

There is no API-key path into agent/workflow CRUD — that always needs a JWT. Runtime integrators almost always want the API-key → session-token flow, not JWT.

## The core runtime flow

```graphql
mutation {
  sdkStart(input: { agentId: 1, clientId: "user-123" }) {
    sessionId
    avatarToken
  }
}
# → then, using avatarToken as the Bearer token:
mutation {
  sdkSendMessage(input: { sessionId: 1, text: "Hello" })
}
```

`sdkSendMessage` returns immediately — it's an ACK, not the reply. The actual reply streams asynchronously over a GraphQL subscription (`sessionEvents(sessionId)`), watching for `AiResponseEvent`. This trips up almost every first integration — don't poll or assume a synchronous reply.

**Subscription gotcha:** `sessionEvents` returns a union type. You MUST explicitly select every member type with `... on TypeName { fields }` — Apollo silently drops any type you don't select, with zero error. If events seem to vanish, check your selection set first.

## Workflows — the node/edge model

A workflow is `{ nodes: [...], edges: [...] }`. Node types (lowercase): `start`, `llm`, `condition`, `router`, `response`, `webhook`, `tool`, `action`, `end_session`.

Two gotchas that will burn you immediately:

1. **`createWorkflow` returns an EMPTY graph** — no `nodes`/`edges` input field exists on it. Add the real graph via a second `updateWorkflow(id, { nodes, edges })` call.
2. **A workflow does nothing until `publishWorkflow(id)` is called explicitly** — even with a perfectly valid graph and the agent's `workflowId` correctly set, an unpublished workflow silently produces a generic failure reply for every message. If a workflow "does nothing, no error," check `isPublished` first.

`nodes`/`edges` are `GraphQLJSON` scalars — always send them via a GraphQL `variables` block, never inline in the query string (inline literal JSON syntax doesn't parse).

**`condition` nodes use `expr-eval`, NOT JavaScript** — `==`/`!=` not `===`/`!==`, `and`/`or`/`not` not `&&`/`||`/`!`, bare flat variable names only (no `context.x` property access). Outgoing edges must be labeled exactly `'true'`/`'false'` (lowercase strings) or that branch never fires.

## Common mistakes (check these before deep-diving into a bug)

- Missing `x-huat-platform: customer` header (see above).
- Treating `sdkSendMessage`'s return as the AI's reply — it's not, subscribe instead.
- Forgetting union-type selections on the events subscription.
- Building a workflow via `createWorkflow` and expecting it to accept the graph directly — it doesn't, use `updateWorkflow`.
- Forgetting to `publishWorkflow` after editing an existing one.
- Writing `condition` node expressions as real JavaScript.
- Putting an API key in client-side/browser code — proxy it through your own backend instead.

## Where to look next

- Full GraphQL field reference (every query/mutation, real request/response examples): https://wetel.dev/docs/api-reference/overview/
- Workflow node-by-node reference + worked full-graph examples: https://wetel.dev/docs/workflows/overview/ and https://wetel.dev/docs/workflows/examples/
- Troubleshooting / debugging a failed workflow run: https://wetel.dev/docs/troubleshooting/

Keeping it current

This skill is a hand-maintained summary — if Wetel’s API changes in a way that would make something above wrong, the live docs are always the source of truth. Check the Changelog if something here seems out of date.