Step 1: Send a verification code to the user's Pine AI email.

After calling this, ask the user to check their email (including spam) and provide the code. Then call pine_auth_verify_code with the code and the returned request_token.

Step 2: Verify the email code and activate Pine AI credentials.

Use the request_token from pine_auth_request_code and the code the user received. On success, all Pine tools become available.

Create a new Pine AI session to start a customer service task.

Returns session_id and web URL. Next step: call pine_send_message with the user's request (e.g. "Negotiate my Comcast bill").

List Pine AI sessions with optional state filter.

Args: state: Filter by state (e.g. "init", "task_ready", "in_progress"). limit: Max sessions to return (default 30). offset: Pagination offset.

Get session details including state, title, and timestamps.

Delete a Pine AI session.

Args: session_id: The session to delete. force_delete: If True, force-delete even if the session has an active task.

Get the web URL for a session. Share with the user for progress tracking, payments, or credits.

Poll Pine's conversation history — the core way to see replies (no streaming).

Call after sending a message or starting a task. Wait a few seconds between polls. Look for: [FORM], [BILLING], [PAYMENT], [TASK READY], [CREDITS NEEDED], [AUTH NEEDED], [THREE-WAY CALL], [TASK FINISHED], [ACTION NEEDED].

Args: session_id: The session to load history for. max_messages: Max messages to fetch (default 30). order: "asc" (oldest first) or "desc" (newest first). from_message_id: Fetch messages after this ID (for pagination).

Send a message to Pine AI — describe the task, answer questions, or provide info.

Also used to submit form answers as JSON ({"field_name": "value"}) when pine_send_form_response is not applicable. Use pine_get_history afterward to see Pine's response.

Args: session_id: The session to send the message to. content: Text message or JSON form data to send. attachments: Optional attachment metadata from pine_upload_attachment.

Submit a form shown in pine_get_history as [FORM].

Fill fields you know; ask the user for unknowns (especially preferences or security info). Use exact option labels for select fields.

Args: session_id: The session containing the form. message_id: The form's message_id from pine_get_history output. form_data: {"field_name": "value"} pairs matching the form fields.

Submit an OTP/verification code for an [AUTH NEEDED] event.

ALWAYS ask the user for the code first — never guess or hallucinate OTPs, PINs, or security answers.

Args: session_id: The session requesting authentication. message_id: The auth request's message_id from pine_get_history. data: Verification data, e.g. {"code": "123456"}.

Submit location coordinates for a [LOCATION NEEDED] event. Ask the user if unknown.

Args: session_id: The session requesting the location. message_id: The location request's message_id from pine_get_history. latitude: Latitude string (e.g. "37.7749"). longitude: Longitude string (e.g. "-122.4194").

Submit a location selection from options Pine provided.

Args: session_id: The session with the location selection. message_id: The location selection request's message_id. places: Selected place objects from Pine's provided options.

Start task execution after billing is confirmed.

Only call after: [BILLING] free task, [BILLING] payment received, or [PAYMENT] completed. Do NOT call if [TASK READY] says credits confirmed/auto-started — the task is already running.

Stop a running Pine AI task.

Upload a file (bill, screenshot, document) for a Pine AI session.

Returns attachment metadata — pass it to pine_send_message via the attachments parameter to include the file in a message.

Args: file_path: Absolute path to the file to upload.

Delete a previously uploaded attachment.

Args: attachment_id: The attachment ID from pine_upload_attachment.

Share completed task results on social media to earn Pine credits.

Args: session_id: The completed session to share results from. platform: One of "x", "facebook", or "linkedin". shared_url: The URL of the social media post.

Update a scheduled call reminder. Confirm timing with the user first.

Args: session_id: The session with the scheduled call. message_id: The call reminder's message_id. scheduled_time: ISO 8601 datetime for the call. enabled: True to enable, False to disable.