← Back to Documentation

Node.js Quickstart

Make your product callable by phone in under 5 minutes. Aployee handles the conversation; your backend handles the reasoning.

Prerequisites
# Prerequisites
# - Node 18+ (for webhook handler)
# - Public HTTPS endpoint (use ngrok in dev)
# - Aployee API key
1

Create an assistant

An assistant is a callable voice agent. You define its name, system prompt, personality, and reasoning mode. For webhook mode, Aployee sends you context and you return business decisions.

Terminal
curl https://api.aployee.com/v1/assistants \
  -H "Authorization: Bearer $APLOYEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SupportBot",
    "system_prompt": "You are a calm, competent support rep.",
    "personality": {
      "formality": "neutral",
      "assertiveness": "medium",
      "empathy": "medium",
      "talkativeness": "medium"
    },
    "reasoning_mode": "webhook",
    "webhook_url": "https://your-domain.com/aployee"
  }'

# Save the returned assistant_id
2

Handle reasoning in your backend

Your webhook receives the user's utterance and conversation state. You return an optional reply and updated state. If you don't return a reply, Aployee's conversation agent handles it automatically.

server.ts
import express from "express";
const app = express();
app.use(express.json());

app.post("/aployee", async (req, res) => {
  const { utterance, state } = req.body;

  let newState = { ...state };

  // Example: simple account lookup
  if (utterance.includes("balance")) {
    const balance = await lookupAccountBalance(state.userId);
    newState.lastBalance = balance;

    return res.json({
      reply: `Your current balance is ${balance} dollars. Anything else?`,
      state: newState
    });
  }

  // Fallback: let Aployee's conversation agent handle it
  return res.json({
    reply: "Can you tell me more?",
    state: newState
  });
});

app.listen(3000, () => console.log("Webhook running on 3000"));

Webhook payload

  • utterance - What the user just said
  • state - JSON object persisted across the call
  • context - Recent dialogue history
3

Make a call

Start a call with your assistant. The call begins immediately. You can inspect the live transcript, timeline, audio, and webhook traces in the dashboard.

Terminal
curl https://api.aployee.com/v1/calls \
  -H "Authorization: Bearer $APLOYEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_xxxx",
    "to": "+15551234567"
  }'

# The call begins immediately.
# View transcript, timeline, and webhook traces in the dashboard.

How the dual-agent architecture works

  1. Conversation agent handles real-time speech with sub-300ms latency. Manages turn-taking, interruptions, and keeps dialogue flowing.
  2. Reasoning agent (your webhook) runs async in parallel. When it returns, results blend into the next natural turn.
  3. State persists across the call. Your webhook can read and update it to track context, entities, and call progress.

Next steps