How conversations reach your agent

Pip is always the first voice a user hears. When a user asks for your agent by name, Pip routes the conversation to your webhook. Here's the full lifecycle.

1. Discovery

The user says something like "Hey Pip, connect me with George" or "Find me an agent that can help with home repair." Pip searches the agent directory and, if the user confirms, initiates a connection.

2. Connect intro

Your webhook receives a first request with the sentinel text __pipbit_agent_connected__. Use req.is_connect_intro() to detect this and return a greeting.

If the user included a question in their connect request (e.g. "Hey George, how do I change a light bulb?"), your webhook receives the full utterance as req.text instead of the sentinel. In that case, skip the greeting and answer directly.

3. Conversation turns

Each subsequent user utterance arrives as a POST to your webhook with the transcribed text, conversation history, user identity, and device state. Return a spoken response or defer for async processing.

4. Handback to Pip

The conversation returns to Pip when:

• The user says "Pass me back to Pip"
• Your agent returns a response that signals handback
• The user starts a new session

Pip will acknowledge the return with a brief, natural transition and resume as the primary assistant.

Nicknames

When you register your agent, you set a suggested name — the default name users use to reach your agent by voice. However, users can override this with a personal nickname.

For example, a user might say "Hey Pip, can I call George something else? Let's call him G." From then on, that user reaches your agent by saying "G" instead of "George." Nicknames are per-user and don't affect other users or your agent's registered identity.

Authentication modes

You control how users authenticate with your agent. Options are configured in the developer portal:

Mode	How it works
None (public)	Any Pipbit user can talk to your agent with no credentials.
Voice credentials	User speaks a username and password. Best with spelled-out credentials.
Voice + email link	User speaks a username, then Pipbit emails them a verification link hosted by you.
Voice + SMS code	User speaks a username, then receives an SMS verification code.
OAuth / web redirect	Pipbit sends the user a link to your OAuth consent page. Best for services like Spotify, Ring, or banking.