Outbound and scheduling

Hyponema agents can do more than answer inbound calls. They can place outbound calls, schedule one-off callbacks for a specific user, and run recurring check-ins on a weekday + local-time pattern. The agent itself can reschedule or cancel a callback during a conversation.

This is the operator side of telephony — for the carrier setup, see Telephony.

Phone numbers

Each phone number you provision lives at the workspace level and can be attached to one agent at a time. Inbound calls to that number ring the attached agent. Outbound calls placed on behalf of the agent show that number as the caller ID.

Manage numbers from Distribute → Phone in the dashboard, or:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/phone-numbers" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

POST to add a new number against a configured carrier; DELETE to release.

Schedules

A schedule is a Hyponema-side rule that places an outbound call to a user. Two shapes:

Kind	Fields
Recurring	weekdays, local_time, timezone, enabled
One-shot	run_at (UTC), enabled

Each schedule binds an agent_id and a user_id. The schedule poller worker fires due rows, places the call against the agent’s attached phone number, and records last_run_at / next_run_at.

max_attempts and retry_delay_seconds control retry behavior when the user does not answer.

Operator-authored schedules

Open Distribute → Schedules to create a schedule from the dashboard. Pick the agent, the user, and either a weekday + local-time pattern or a one-off run_at.

Or via API:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/schedules" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "user_id": "user_...",
    "single_shot": false,
    "weekdays": [1, 3, 5],
    "local_time": "09:30:00",
    "timezone": "Europe/Madrid",
    "max_attempts": 3,
    "retry_delay_seconds": 600
  }'

weekdays follow the ISO 1–7 (Monday–Sunday) convention. single_shot: true requires run_at instead of weekdays + local_time.

Agent-authored schedules

Two built-in tools let the agent schedule and manage callbacks during a conversation:

• schedule_callback — dials PSTN minutes. Off by default per agent. Turn it on through the agent’s Tools tab when you want the agent to be able to commit to a follow-up call (“I’ll call you back tomorrow at 10”).
• manage_callback — list, cancel, or reschedule existing entries, including operator-authored recurring schedules. Same opt-in as above.

When enabled, the agent can call these tools during the turn just like any other tool. The trace shows the tool call with the proposed run_at and the resulting schedule row.

Outbound calls without a schedule

For a one-off outbound dial, create a one-shot schedule with run_at close to “now”. Sub-minute precision is not guaranteed — the worker polls on an interval — so a true real-time outbound campaign should batch through schedules.

Listing and inspecting

GET /workspaces/{ws}/schedules lists schedules with optional filters. The dashboard shows them grouped by agent with the next firing time and the last run status.

GET /workspaces/{ws}/schedules/{id}/occurrences (where exposed) previews upcoming firing times for a recurring schedule.

What the user experiences

When an outbound call connects, the user picks up and the agent’s persona greeting plays. From the agent’s point of view it’s the same session pipeline as inbound — same persona, same memory, same tools, same observability — only the call origination differs.

If the call is missed, the schedule’s retry policy kicks in. If max_attempts is exhausted, the schedule is marked accordingly and not retried again.

Operational guidance

• Test in your dev workspace first. Outbound dialing burns PSTN minutes and may surprise users.
• Pin schedules to the user’s timezone, not yours. The user-local time-of-day field on the user record drives local_time.
• Keep recurring schedules short-lived for new agent versions until you’ve validated post-call extraction in production traces.
• If a schedule fires when the user is mid-conversation on another channel, Hyponema does not double-call — the existing live session takes precedence.