Resources

The client exposes four resources: agents, workflows, conversations, and calls. Every method returns a typed result, and the list methods return a value you can both await and iterate (see Pagination).

Agents

await bimpe.agents.list({ page: 2, limit: 50, search: 'support', sort: '-created_at' });
const created = await bimpe.agents.create(
  { workflow_id: workflowId, name: 'Support bot', description: 'Tier 1 support' },
  { idempotencyKey: 'op-1' },
);
const detail = await bimpe.agents.retrieve(created.id);
await bimpe.agents.update(created.id, { description: 'Updated' });
await bimpe.agents.updateLiveStatus(created.id, { status: 'live' });

list returns a PagePromise<Agent>. create takes CreateAgentBody (workflow_id, name, and description are required; persona, language, timezone, logo, the business_* fields, and escalation_email are optional) and returns an AgentCreateResponse, which is an Agent plus the nested workflow it was created from; created.id is the new agent's id. update takes a partial UpdateAgentBody and returns an Agent. updateLiveStatus moves the agent between development, live, and paused and returns the new AgentLiveStatus. retrieve returns an AgentDetail, which is an Agent plus the agent's integrations, channels, and knowledge bases inlined. delete removes the agent permanently and resolves to void. Only create accepts per-call RequestOptions.

Sub-resources

integrations and channels are read-only through the API; connect and configure them in the Console dashboard. Actions are listable and can also be enabled or disabled in bulk by id. Each list method returns an array, not a page. channels.list items are AgentChannel objects (id, type, name, status, is_connected), where type is the channel kind, such as whatsapp, instagram, messenger, webchat, voice, or telephony.

await bimpe.agents.integrations.list(agentId);
await bimpe.agents.channels.list(agentId);

await bimpe.agents.actions.list(agentId);
await bimpe.agents.actions.enable(agentId, { action_ids: ['act_1', 'act_2'] });
await bimpe.agents.actions.disable(agentId, { action_ids: ['act_3'] });

To inspect an agent's conversation flows, read them from its workflow: (await bimpe.workflows.retrieve(workflowId)).flows.

Knowledge bases

Knowledge bases support full CRUD. The create body is a text source or a URL source, told apart by its type. Reads and writes return a KnowledgeBaseItem, which carries that same type field (text or url).

await bimpe.agents.knowledgeBases.list(agentId);
await bimpe.agents.knowledgeBases.create(agentId, { type: 'text', name: 'FAQ', content: '…' });
await bimpe.agents.knowledgeBases.create(agentId, { type: 'url', name: 'Docs', url: 'https://…' });
await bimpe.agents.knowledgeBases.update(agentId, kbId, { description: '…' });
await bimpe.agents.knowledgeBases.delete(agentId, kbId);

Workflows

await bimpe.workflows.list({ scope: 'public', search: 'triage', sort: '-created_at' });
const workflow = await bimpe.workflows.create(
  { name: 'Triage', system_prompt: 'You triage incoming support requests.' },
  { idempotencyKey: 'op-2' },
);
const copy = await bimpe.workflows.clone({ source_workflow_id: workflow.id });
await bimpe.workflows.retrieve(workflow.id);
await bimpe.workflows.update(workflow.id, { tags: ['v2'] });
await bimpe.workflows.delete(workflow.id);

scope is owned, public, or accessible. create takes CreateWorkflowBody, where name and system_prompt are required and rules, flows, tags, category, guide, faq, and setup_steps are optional. clone copies an existing workflow named by source_workflow_id. list, retrieve, create, and update all return a full Workflow, which carries system_prompt, rules, flows, tags, guide, faq, setup_steps, and the rest of the template. Only create and clone accept per-call RequestOptions.

Conversations and messages

await bimpe.conversations.list(agentId, { channel: 'whatsapp', search: 'invoice' });
await bimpe.conversations.retrieve(agentId, conversationId);

await bimpe.conversations.messages.list(agentId, conversationId);
const message = await bimpe.conversations.messages.retrieve(agentId, conversationId, messageId);
const sent = await bimpe.conversations.messages.send(agentId, conversationId, { message: 'Hello' });

await bimpe.conversations.setAiStatus(agentId, conversationId, { is_ai_chat_paused: true });
await bimpe.conversations.send(agentId, {
  message: 'Hello again',
  channel_type: 'whatsapp',
  channel_user_id: '2348012345678',
});

channel accepts whatsapp, webchat, telephony, and the test_* variant of each. conversations.list returns a PagePromise<Conversation> and messages.list returns a PagePromise<Message>. messages.send replies into an existing conversation: it takes SendMessageBody (message plus optional role, where role: 'assistant' is a human reply that only takes effect while the AI is paused), accepts per-call RequestOptions, and returns the created Message. conversations.send is the agent-scoped variant that seeds or finds a conversation by channel identity (channel_type, channel_user_id) and replies into it; conversations.setAiStatus pauses or resumes the AI for one conversation.

Calls

calls is a top-level resource, but every method is scoped to an agent by its first argument. make places an outbound call, list pages over an agent's calls, and retrieve returns a CallDetail (the call plus its conversation_logs).

await bimpe.calls.list(agentId);
const result = await bimpe.calls.make(agentId, { destination: '+15551234567', is_test_call: true });
await bimpe.calls.retrieve(agentId, callId);

make takes MakeCallBody (destination plus is_test_call). With is_test_call: true the call runs on BimpeAI's test telephony; with is_test_call: false it goes out over a live telephony channel, which you connect and configure in the Console dashboard. list returns a PagePromise<Call>.

Phone numbers

phoneNumbers is a top-level, team-scoped resource. You request a number, and once one is assigned you link it to an agent; the nested phoneNumbers.requests resource handles provisioning requests.

// Request a number (provisioning is fulfilled by BimpeAI).
await bimpe.phoneNumbers.requests.create({
  business_name: 'Acme Support Ltd',
  intended_use: 'Inbound customer support',
  region: 'ng',
  agent_count: 1,
  outbound_minutes: 500,
});
await bimpe.phoneNumbers.requests.list();

// List assignments, then link one to an agent and label it.
const numbers = await bimpe.phoneNumbers.list();
const detail = await bimpe.phoneNumbers.retrieve(numbers.data[0]!.id);
await bimpe.phoneNumbers.update(detail.id, { agent_id: agentId, label: 'Support line' });

phoneNumbers.list and requests.list return a PagePromise<PhoneNumber> (id, agent_id, label, e164). requests.create takes a CreatePhoneNumberRequestBody (business_name, intended_use, region of 'us' | 'uk' | 'eu' | 'ng', agent_count, outbound_minutes, and optional submitted_by_agent_id) and returns nothing. retrieve and update return a PhoneNumberDetail, which is a PhoneNumber plus created_at, updated_at, and inbound_enabled. update takes an UpdatePhoneNumberBody (agent_id, where null unassigns, and label). A number linked to an agent is the live telephony channel that calls.make({ is_test_call: false }) dials out over.