Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

HookMyApp home pagelight logodark logo
  • GitHub
  • Agent Skills
  • npm

Getting started

  • Introduction
  • Quickstart
  • Build with AI
  • Agent setup
  • Personal AI agent
  • OpenClaw
  • Hermes Agent

Sending & receiving

  • Connect WhatsApp
  • Receive webhooks
  • Sandbox
  • Webhook routing
  • Event subscriptions

Tools

  • Development advice
  • CLI
  • Agent skills
  • MCP
  • Support from your agent

Self-managed setup

  • Manual Meta setup

FAQs

  • Payment issues
  • Pricing
  • Display names

API Reference

  • API overview
  • Support
  • App
WhatsApp
Instagram
Facebook
SaaS Mode
HookMyApp home pagelight logodark logo
  • Support
  • App
  • App
WhatsApp
Instagram
Facebook
SaaS Mode
Getting started

Agent setup

The setup instructions for your AI coding agent. Give your agent this page and it does the rest.

Set up HookMyApp for me. Follow these steps:

Before you start, one rule for network errors. If a command below fails with ENOTFOUND, EAI_AGAIN, ECONNREFUSED, ENETUNREACH, EHOSTUNREACH, ETIMEDOUT or ECONNRESET, you are probably in a sandbox without internet access, so ask me to allow network access. Then:
- ENOTFOUND, EAI_AGAIN, ECONNREFUSED, ENETUNREACH or EHOSTUNREACH: the request never left this machine, so run the same command again, whatever it is.
- ETIMEDOUT or ECONNRESET on a hookmyapp command that signs in or sends or checks a code (login, alerts phone set, alerts phone verify): do not rerun it, because the request may have reached HookMyApp and these steps cannot be repeated safely. For alerts phone, run hookmyapp alerts phone status to see whether it took effect and continue from there. For login, stop and tell me the exact error; do not continue on a sign-in you cannot confirm. The one exception is the step 4 code request (hookmyapp login --email <my email> --json): run that again, even though step 4 says exactly once. While the first code is still valid it returns the same registrationId and does not send another code.
- ETIMEDOUT or ECONNRESET on any other command (npm, npx, or any other hookmyapp command): run it again.
Only if a command still fails with network access allowed, follow that step's own failure rule.

1. Check prerequisites. You need Node.js 20 or newer (npm ships with it):
   node -v
   If node is missing or below v20, STOP: every step below is a CLI command, so this setup cannot run without it. Tell me to install the current LTS from https://nodejs.org and re-run. Tell me the alternative too, in case I do not want Node on this machine: I can create the account at https://staging-app.hookmyapp.com and drive it from the hosted MCP server (https://api.hookmyapp.com/mcp) or the REST API with an API key, no CLI involved.

2. Install the HookMyApp agent skills globally so this and future agent sessions know how to finish or recover the setup:
   npx skills add hookmyapp/agent-skills --all --global
   If the command fails, continue anyway: step 5 runs the same install again and usually repairs it. Only if it fails there too, tell me to run the skills command myself.

3. Install the HookMyApp CLI. Run this even if hookmyapp is already installed, so it upgrades to the latest version:
   npm install -g @gethookmyapp/cli
   On macOS or Linux, if it fails with EACCES (permission denied) on npm's global folder (the path in the error is inside the output of npm config get prefix, usually /usr/local), do not use sudo. Move npm's global folder into my home directory and install again:
   npm config set prefix ~/.npm-global
   npm install -g @gethookmyapp/cli
   Then put ~/.npm-global/bin on my PATH for new terminals: add export PATH="$HOME/.npm-global/bin:$PATH" to my shell startup file (~/.zshrc for zsh; for bash, the existing file my terminal actually loads, such as ~/.bash_profile, ~/.bash_login, ~/.profile or ~/.bashrc, and never create a new ~/.bash_profile; for fish, csh or another shell, use that shell's own syntax instead, such as fish_add_path ~/.npm-global/bin) so hookmyapp stays on my PATH in new terminals, and tell me you did. If this install fails too, or EACCES names any other path, STOP and tell me the exact error.
   If hookmyapp is then not found (command not found), the install still worked: agent shells often do not read my shell startup file. Do not stop. On macOS or Linux, run npm prefix -g and use the folder it prints plus /bin/hookmyapp as the full path for every hookmyapp command in this setup.

4. Sign me in. This also creates my free HookMyApp account if I don't have one yet. Look for email addresses that are likely mine (git config user.email, prior context). If you found any, ask me: "Your free HookMyApp account needs an email address. Should I use <the email(s) you found>, or a different one?" If you found none, ask me: "To set up your free HookMyApp account I need an email address. Which one should I use?" Either way, keep it to that one question, with no commands and no mention of where you looked. Once I confirm, run:
   hookmyapp login --email <my email> --json
   Run that initiation command exactly once. Save its registrationId and do not request another code. A 6-digit code is sent to my email. Tell me: "I just sent a 6-digit sign-in code to <email>. Paste it here so I can finish setting up your HookMyApp account." Any unexpired code sent to that same email during this 10-minute login window is valid. Complete with:
   hookmyapp login --email <my email> --registration-id <the saved registrationId> --otp <the 6-digit code> --json
   Use the hookmyapp CLI for everything until the MCP tools are live (see the HookMyApp skill).

5. Set yourself up to use HookMyApp directly:
   hookmyapp agent setup
   This connects the HookMyApp MCP server to every coding agent installed on this machine, with access already granted, so no agent needs a separate sign-in. It also re-runs the skills install from step 2, which repairs it if that step failed. It prints one line per agent naming the restart that agent needs. Do only what it names for you.
   Do not try to prove this worked by calling a HookMyApp MCP tool now. You loaded your MCP servers when this session started, so any hookmyapp tool you can see is the old configuration and calling it proves nothing. Tell me to restart you instead.

6. Confirm the setup:
   hookmyapp doctor
   If doctor reports an error or exits non-zero, STOP and tell me what failed.

7. Set my alert phone so HookMyApp can reach me when the integration breaks later:
   hookmyapp alerts phone status
   If that already shows a verified number, skip this step. Otherwise tell me why before asking: HookMyApp texts this number (WhatsApp or SMS) when my webhooks start failing, a channel disconnects, or my plan limit is reached, so I find out even when I am not watching the logs. Then ask me for the number and run:
   hookmyapp alerts phone set <the number I give you>
   hookmyapp alerts phone verify <the 6-digit code I read back to you>
   Never invent the number or the code; both come from me. If I decline, skip it and continue; nothing downstream depends on it.

   Only after doctor succeeds, tell me setup is done. Also tell me to restart you, which is what makes the HookMyApp MCP tools available. The CLI already covers everything in the meantime.

If anything fails and its step does not say how to recover, STOP, preserve the registrationId, and tell me the exact error. Do not run the initiation command again or request another code unless all existing codes are expired or locked and I explicitly approve another email. The network-error rule at the top is the only exception: its rerun of the code request reuses the same code.
Previous
Personal AI agent
Connect your own WhatsApp number to your own AI agent.
Next
⌘I
github
Powered byThis documentation is built and hosted on Mintlify, a developer documentation platform