Resources

The client exposes four resources: agents, workflows, conversations, and calls. Every method returns a typed result, and the list methods return a Page you can both iterate directly and walk page-by-page (see Pagination).

Agents

agents = client.agents.list(page=2, limit=50, search="support", sort="-created_at")
created = client.agents.create(
    workflow_id=workflow_id,
    name="Support bot",
    description="Tier 1 support",
    idempotency_key="op-1",
)
detail = client.agents.retrieve(created.id)
client.agents.update(created.id, description="Now tier 2 as well")
client.agents.update_live_status(created.id, status="live")

list returns a Page[Agent]. create and update take the agent fields as keyword arguments (workflow_id, name, description, language, persona, timezone, logo, the business_* fields, and escalation_email); workflow_id, name, and description are required on create, and every field is optional on update. create returns an AgentCreateResponse, which is an Agent plus the nested workflow it was created from (created.id is the new agent's id); update returns an Agent. update_live_status moves the agent between development, live, and paused and returns an 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 returns None.

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 a plain list. 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.

client.agents.integrations.list(agent_id)
client.agents.channels.list(agent_id)

client.agents.actions.list(agent_id)
client.agents.actions.enable(agent_id, action_ids=["act_1", "act_2"])
client.agents.actions.disable(agent_id, action_ids=["act_3"])

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

Knowledge bases

Knowledge bases support full CRUD. The create body is a text source or a URL source, distinguished by its type, and is passed as a single dict so the union stays well typed. Reads and writes return a KnowledgeBaseItem, which carries that same type field (text or url).

client.agents.knowledge_bases.list(agent_id)
client.agents.knowledge_bases.create(agent_id, {"type": "text", "name": "FAQ", "content": "..."})
client.agents.knowledge_bases.create(agent_id, {"type": "url", "name": "Docs", "url": "https://..."})
client.agents.knowledge_bases.update(agent_id, kb_id, description="Updated")
client.agents.knowledge_bases.delete(agent_id, kb_id)

Workflows

workflows = client.workflows.list(scope="public", search="triage", sort="-created_at")
workflow = client.workflows.create(
    name="Triage",
    system_prompt="You triage incoming support requests.",
    idempotency_key="op-2",
)
copy = client.workflows.clone(source_workflow_id=workflow.id)
client.workflows.retrieve(workflow.id)
client.workflows.update(workflow.id, tags=["v2"])
client.workflows.delete(workflow.id)

scope is owned, public, or accessible. create takes the workflow fields as keyword arguments, 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.

Conversations and messages

conversations = client.conversations.list(agent_id, channel="whatsapp", search="invoice")
conversation = client.conversations.retrieve(agent_id, conversation_id)

messages = client.conversations.messages.list(agent_id, conversation_id)
message = client.conversations.messages.retrieve(agent_id, conversation_id, message_id)
sent = client.conversations.messages.send(agent_id, conversation_id, message="Hello")

client.conversations.set_ai_status(agent_id, conversation_id, is_ai_chat_paused=True)
client.conversations.send(
    agent_id,
    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 Page[Conversation] and messages.list returns a Page[Message]. messages.send replies into an existing conversation: it takes message plus optional role (where role="assistant" is a human reply that only takes effect while the AI is paused) 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.set_ai_status 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).

client.calls.list(agent_id)
result = client.calls.make(agent_id, {"destination": "+15551234567", "is_test_call": True})
client.calls.retrieve(agent_id, call_id)

make takes a MakeCallBody dict (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 Page[Call].

Phone numbers

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

# Request a number (provisioning is fulfilled by BimpeAI).
client.phone_numbers.requests.create(
    business_name="Acme Support Ltd",
    intended_use="Inbound customer support",
    region="ng",
    agent_count=1,
    outbound_minutes=500,
)
client.phone_numbers.requests.list()

# List assignments, then link one to an agent and label it.
numbers = client.phone_numbers.list()
detail = client.phone_numbers.retrieve(numbers.data[0].id)
client.phone_numbers.update(detail.id, agent_id=agent_id, label="Support line")

phone_numbers.list and requests.list return a Page[PhoneNumber] (id, agent_id, label, e164). requests.create takes the request fields as keyword arguments (business_name, intended_use, region of "us" | "uk" | "eu" | "ng", agent_count, outbound_minutes, and optional submitted_by_agent_id) and returns None. retrieve and update return a PhoneNumberDetail, which is a PhoneNumber plus created_at, updated_at, and inbound_enabled. update takes agent_id (pass None to unassign) and label as keyword arguments. A number linked to an agent is the live telephony channel that calls.make dials out over when is_test_call is False.