.. _quickstart:

Quick Start
===========

This page gets you from zero to a working WhatsApp bot in about five minutes.

Prerequisites
-------------

Make sure you have completed the :doc:`installation` steps -- in particular
``pip install astra-engine[qr]`` and ``python -m playwright install chromium``.

Your first bot
--------------

Create a file called ``bot.py``:

.. code-block:: python

   import asyncio
   from astra import Client, Filters

   async def main():
       # session_id saves your auth so you only scan QR once
       async with Client(
           session_id="mybot",
           phone="+911234567890",   # or omit for QR-only auth
           headless=False,          # set True after first auth
       ) as client:

           @client.on_message(Filters.command(".ping"))
           async def ping(msg):
               await msg.respond("Pong!")

           @client.on_message(Filters.command(".echo"))
           async def echo(msg):
               text = msg.text.replace(".echo", "").strip()
               await msg.reply(text or "Say something after .echo")

           await client.run_forever()

   if __name__ == "__main__":
       asyncio.run(main())

Run it:

.. code-block:: bash

   python bot.py

First run
---------

On the first run the browser will open and you will either:

1. **Phone pairing** -- if you supplied a ``phone`` number, you will see a
   pairing code in the terminal.  Open WhatsApp on your phone, go to
   *Linked Devices > Link a Device*, and enter the code.

2. **QR code** -- if no phone number is set, a QR code appears in your
   terminal.  Scan it from WhatsApp's *Linked Devices* screen.

Once authenticated, your session is saved in ``.astra_sessions/``.
Subsequent runs can use ``headless=True`` without scanning again.

Sending a message
-----------------

Inside any handler, you can send messages through the client:

.. code-block:: python

   # Reply in the same chat
   await msg.respond("Hello!")

   # Reply quoting the original message
   await msg.reply("Replying to you!")

   # Send to a specific chat by JID
   await client.chat.send_message("1234567890@c.us", "Hi there")

What is a JID?
--------------

WhatsApp identifies every chat with a **JID** (Jabber ID):

- **Personal chats**: ``<phone>@c.us`` -- e.g. ``911234567890@c.us``
- **Groups**: ``<id>@g.us`` -- e.g. ``120363012345678@g.us``
- **Linked devices**: ``<id>@lid`` -- internal device JID

You get the JID from ``msg.chat_id`` in any handler.

Stopping the bot
----------------

Press ``Ctrl+C`` in the terminal.  Astra shuts down the browser and saves
session state automatically.

Next steps
----------

- :doc:`core_concepts` -- understand the lifecycle, bridge, and session model
- :doc:`usage` -- chat, group, account, and media operations
- :doc:`filters` -- advanced message matching
- :doc:`error_codes` -- every error code explained
