Skip to main content
The Agents resource provides complete control over your AI agents—from creation to deployment.

​
Overview

client.agents.list(params?)      // List all agents
client.agents.get(id)            // Get a single agent
client.agents.create(input)      // Create a new agent
client.agents.update(id, input)  // Update an agent
client.agents.delete(id)         // Delete an agent
client.agents.deploy(id, input)  // Deploy to WhatsApp
client.agents.share(id, input)   // Share with another user
client.agents.unshare(id, input) // Remove sharing

​
List Agents

Retrieve all agents you have access to. 
const { data: agents, totalCount, hasMore } = await client.agents.list({
  offset: 0,
  limit: 20,
});

console.log(`Found ${totalCount} agents`);
agents.forEach(agent => {
  console.log(`- ${agent.name} (${agent.id})`);
});

​
Parameters

ParameterTypeDescription
offsetnumberNumber of items to skip (default: 0)
limitnumberMaximum items to return (default: 20)

​
Response

interface PaginatedResponse<Agent> {
  data: Agent[];
  totalCount: number;
  hasMore: boolean;
}

​
Get Agent

Retrieve a single agent with all nested resources. 
const agent = await client.agents.get('agent-uuid');

console.log(agent.name);
console.log(agent.systemPrompt);
console.log(`Has ${agent.tools.length} tools`);
console.log(`Has ${agent.documents.length} documents`);

​
Response Type

interface Agent {
  id: UUID;
  name: string;
  description: string;
  systemPrompt: string;
  firstMessage: string;
  profilePicture: ImageInfo | null;
  icebreakers: string[];
  
  // Nested resources
  tools: AgentTool[];
  documents: AgentDocument[];
  memoryKeys: AgentMemoryKey[];
  wakeUpConfigs: AgentWakeUpConfig[];
  outboundTriggers: AgentOutboundTrigger[];
  websiteTools: AgentWebsiteTool[];
  imageGenerateTools: AgentImageGenerateTool[];
  handoffTools: AgentHandoffTool[];
  mcpConfigs: AgentMcpConfig[];
  
  // Configs
  paywallConfig: AgentPaywallConfig | null;
  adConfig: AgentAdConfig | null;
  creditSettings: AgentCreditSettings | null;
  voiceCallConfig: AgentVoiceCallConfig | null;
  
  // Metadata
  owner: PublicUser | null;
  sharings: PublicUser[];
  phoneNumbers: AgentWhatsAppPhoneNumber[];
  totalMessages: number;
  totalSessions: number;
  connectUrl: string;
  ownerActive: boolean;
  
  createdAt: string;
  updatedAt: string;
}

​
Create Agent

Create a new agent with minimal configuration. 
const agent = await client.agents.create({
  name: 'Customer Support Bot',
});

console.log(`Created agent: ${agent.id}`);
After creation, use update() to add configuration, or use the onboarding methods for AI-assisted setup.

​
Input

FieldTypeRequiredDescription
namestringYesAgent display name

​
Update Agent

Update an agent and all its nested resources. Pass the full configuration—nested resources are fully replaced. 
const updated = await client.agents.update(agentId, {
  name: 'Updated Name',
  systemPrompt: 'You are a helpful assistant...',
  firstMessage: 'Hello! How can I help you today?',
  icebreakers: ['What can you help me with?', 'Tell me about your services'],
  
  // Update tools (replaces all existing tools)
  tools: [
    {
      name: 'check_order',
      description: 'Look up order status',
      apiSchema: { /* ... */ },
      active: true,
    },
  ],
  
  // Update paywall config
  paywallConfig: {
    messageLimit: 10,
    paywallAction: 'purchase_link',
    paywallUrl: 'https://example.com/upgrade',
    ctaButtonText: 'Upgrade Now',
  },
});

​
Updating with File Uploads

When updating with files (profile picture or documents), the SDK automatically uses FormData: 
const fileInput = document.getElementById('profile-pic') as HTMLInputElement;

await client.agents.update(agentId, {
  profilePicture: fileInput.files[0],
  documents: [
    {
      name: 'Product Manual',
      file: documentFile,
    },
  ],
});

​
Available Update Fields

{
  name?: string;
  description?: string;
  systemPrompt?: string;
  firstMessage?: string;
  profilePicture?: File | null;
  icebreakers?: string[];
}

{
  tools?: Array<{
    id?: UUID;              // Include to update existing
    name: string;
    description: string;
    apiSchema: Record<string, unknown>;
    active?: boolean;
    creditCost?: number;
  }>;
}

{
  documents?: Array<{
    id?: UUID;
    name: string;
    file: File;
  }>;
}

{
  memoryKeys?: Array<{
    id?: UUID;
    key: string;
    type: 'string' | 'number' | 'boolean' | 'json';
    initialValue: string;
    whenToUpdate: string;
  }>;
}

{
  paywallConfig?: {
    messageLimit?: number | null;
    paywallAction?: 'none' | 'purchase_link' | 'subscribe' | 'terminal';
    paywallUrl?: string | null;
    ctaButtonText?: string;
    terminalStateMessage?: string;
    subscriptionPricePerMonth?: number | null;
  } | null;
}

{
  creditSettings?: {
    initialCredits?: number;
    creditGrantPassword?: string | null;
    creditGrantAmount?: number;
  } | null;
}

​
Delete Agent

Soft-delete an agent. 
await client.agents.delete(agentId);
console.log('Agent deleted');

​
Deploy Agent

Deploy an agent to a WhatsApp phone number. 
const deployed = await client.agents.deploy(agentId, {
  phoneNumberId: 'phone-number-uuid',
});

console.log(`Deployed to: ${deployed.phoneNumbers[0].phoneNumber}`);

​
Input

FieldTypeDescription
phoneNumberIdUUIDThe phone number to deploy to

​
Share Agent

Share an agent with another Wassist user. 
await client.agents.share(agentId, {
  userPhoneNumber: '+1234567890',
});

​
Unshare

Remove sharing with a user. 
await client.agents.unshare(agentId, {
  userPhoneNumber: '+1234567890',
});

​
Complete Example

import { createWassistClient } from '@wassist/sdk';

const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
  authToken: process.env.WASSIST_TOKEN,
});

async function setupCustomerSupportAgent() {
  // Create a basic agent
  const agent = await client.agents.create({
    name: 'Support Bot',
  });
  
  // Configure it fully
  await client.agents.update(agent.id, {
    systemPrompt: `You are a helpful customer support agent for Acme Inc.
    
    Guidelines:
    - Be friendly and professional
    - Answer questions about our products
    - Help with order issues
    - Escalate complex problems to human support
    
    Our return policy: 30 days, original packaging required.
    Support hours: Monday-Friday 9am-5pm EST.`,
    
    firstMessage: "Hi there! 👋 I'm the Acme support assistant. How can I help you today?",
    
    icebreakers: [
      "Track my order",
      "Return an item",
      "Product question",
    ],
    
    tools: [
      {
        name: 'lookup_order',
        description: 'Look up order status by order number (format: ACM-XXXXX)',
        apiSchema: {
          type: 'object',
          properties: {
            endpoint: { type: 'string', const: 'https://api.acme.com/orders/{order_id}' },
            method: { type: 'string', const: 'GET' },
            parameters: {
              type: 'object',
              properties: {
                order_id: { type: 'string', description: 'Order number' }
              },
              required: ['order_id']
            }
          }
        },
        active: true,
        creditCost: 0,
      },
    ],
    
    paywallConfig: {
      messageLimit: 20,
      paywallAction: 'terminal',
      terminalStateMessage: 'Thanks for chatting! For more help, email support@acme.com',
    },
  });
  
  // Deploy to a phone number
  await client.agents.deploy(agent.id, {
    phoneNumberId: 'your-phone-number-uuid',
  });
  
  console.log(`Agent deployed! URL: ${agent.connectUrl}`);
}

Conversations

Manage conversations with your agents.

Concepts: Agents

Understand how agents work.