Guides

Troubleshoot ZeroSettle iMessage in Grok Bot

Grok Bot can’t find ZeroSettle, can read texts but can’t send, or never starts a run when someone replies? Use one conversation on your own Apple phone to find out where the workflow stopped: at the connector, the send attempt, or the webhook routine.

Key takeaways

  • An empty catalog search doesn’t tell you whether a custom connector is installed. Check Your plugins.
  • Run a read-only check first. If a send times out, inspect message history before trying again.
  • An MCP connector works when you ask. A verified relay and webhook routine let a new iMessage start a run.

Find your installed connector first

Start in the Grok Bot desktop app under Connect apps → Your plugins. A search of the app catalog can come back empty even when you already have ZeroSettle installed. In the installed connector’s details, check that the URL is https://portal.zerosettle.io/mcp. Added manually is the expected source for a custom installation.

If it’s missing from your installed plugins, open Connect apps, select Add a custom connector, choose Remote HTTPS, and enter the URL above. Name it ZeroSettle iMessage so you can find it from chat. If a team policy blocks the connector, ask the team admin about access. Grok Bot’s connection instructions.

Confirm the account with a read

An installed connector still needs credentials. If Grok Bot offers a sign-in or reconnect flow, open it and complete the prompts for the ZeroSettle account that owns the line. If your setup uses a static API key, enter it in the connector’s HTTP headers as Authorization: Bearer <token>. Update that field if the key was revoked or replaced, and keep the key out of chat. ZeroSettle’s connection and authentication docs.

Attach the installed connector to a fresh Grok Bot chat using @. Paste this prompt and replace the two placeholders with your ZeroSettle number and a test number you control. If you have several lines, the explicit selector keeps the lookup on the intended number.

Prompt
Use the ZeroSettle iMessage connector for a read-only check.
Call get_line and report whether the account is active and which
ZeroSettle number is selected. Confirm I can access [ZEROSETTLE LINE].
Then check list_messages for [MY TEST NUMBER] on that line. Report the
latest matching test message's ID, time, direction, and status, if found.
If a call fails, report which tool failed and the exact error code or
message. Stop after the reads. Do not send, show typing, change settings,
or include any credentials.

If get_line works but shows the wrong number, check which connector account Grok Bot is using. If the line is inactive, open the ZeroSettle console to check its subscription. If the account is active and the thread is empty, send a test iMessage from your own Apple phone to the ZeroSettle number and run the same prompt again.

Check the send result before trying again

Once the read works, ask Grok Bot to send one clearly labeled test to your own Apple phone. Ask for the result and the message ID. If the Bot is waiting for an approval, handle that first. Once the send runs, use the tool response or ZeroSettle’s message history to decide what to do.

  • Blocked. If you see recipient_opted_out, leave the recipient opted out. If you see awaiting_reply, wait for their first reply. For new_contact_limit, wait for the retry window shown in the error.
  • Still running. Let the tool finish. If it times out, check the same line and thread for a matching outbound message around the time of the attempt. The send can go through after the client stops waiting. Repeating the same text can send it twice.
  • Failed. Read the specific error before deciding whether to retry. Fix a bad recipient address before sending again. For phone_timeout or a dropped connection, reconcile the attempt with message history first.
  • Sent. message_sent or a stored row marked sent records the sending line’s handoff. Check Messages on the receiving Apple phone to confirm that your test arrived.

If the outcome is still unclear, save the line, recipient, approximate send time, and any message ID so you can investigate the original attempt. ZeroSettle’s guide to delivery status and retries.

If chat works but incoming texts never start a run

A custom MCP connection gives Grok Bot tools it can call in chat. For incoming texts to start a run, the line needs to forward inbound events to a relay that verifies ZeroSettle’s signature and calls your Grok Bot webhook routine. Check who manages the line with get_agent. On a line managed by ZeroSettle’s hosted AI agent, direct MCP sends can work while the hosted agent handles replies. A line managed by API sends inbound events to the configured webhook. ZeroSettle’s line management docs.

Send one fresh test from your own Apple phone. Check that the inbound message appears in ZeroSettle, then check the webhook delivery, the relay log, and the routine’s run history in that order. A 200 from Grok Bot’s webhook means the run started. Open the run to see what it did. If it never started, check whether the routine is paused and whether the relay uses the current URL and key. ZeroSettle’s Grok Bot setup guide · Grok Bot’s webhook docs.

Written by the ZeroSettle team. ZeroSettle gives businesses and AI agents a dedicated iMessage number with an API and signed webhooks.

Text your customers from your own iMessage number

ZeroSettle gives your business its own phone number on real iMessage, running on Apple hardware we operate for you. Your code sends with one API call and hears every reply on a signed webhook.

Pro includes one dedicated number. Growth pricing combines a monthly platform fee and a price per line through an invite. Enterprise has custom pricing through sales.