> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with the Convo WhatsApp API in Minutes

> Learn how to authenticate and send your first WhatsApp message using the Convo REST API, no SDK required, just a few curl commands.

By the end of this guide, you'll have authenticated with the Convo API, sent a WhatsApp text message, and verified that it was delivered — all from the command line. No SDK required. Let's go.

<Note>
  Replace `{project_id}` in every URL and `YOUR_API_PASSWORD` in every header with your actual values from the Convo dashboard before running any example.
</Note>

<Steps>
  <Step title="Get your Project API Password">
    Every Convo project has a dedicated **Project API Password** that authenticates your requests. To retrieve yours:

    1. Log in to the [Convo Dashboard](https://app.convo.com).
    2. Navigate to **Settings** → **API & Integrations**.
    3. Copy the value labelled **Project API Password**.

    This value is passed in the `X-API-WA-Project-API-Pwd` header on every request. Keep it secret — treat it like a password.
  </Step>

  <Step title="Find your Project ID">
    Most Convo API endpoints are scoped to a project. Your `project_id` uniquely identifies the WhatsApp number and configuration you want to interact with.

    You can find your `project_id` in two places:

    * **URL bar** — When you open a project in the dashboard, the URL contains your project ID: `https://app.convo.com/project/{project_id}/...`
    * **Project Settings** — Navigate to **Settings** → **Project Details** and look for the Project ID field.

    Copy this value — you'll use it as a path parameter in every API call.
  </Step>

  <Step title="Send a text message">
    With your API password and project ID in hand, you're ready to send your first message. Run the following `curl` command, substituting your real values:

    ```bash theme={null}
    curl -X POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages \
      -H "Content-Type: application/json" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -d '{
        "to": "917089379345",
        "type": "text",
        "recipient_type": "individual",
        "text": {
          "body": "Hello from Convo!"
        }
      }'
    ```

    | Field            | Description                                                                    |
    | ---------------- | ------------------------------------------------------------------------------ |
    | `to`             | Recipient's phone number in E.164 format (country code + number, no `+` sign). |
    | `type`           | Message type — `text` for a plain text message.                                |
    | `recipient_type` | Always `individual` for one-to-one messages.                                   |
    | `text.body`      | The message content, up to 4096 characters.                                    |

    <Note>
      Text messages can only be sent within a 24-hour customer service window — that is, after the user has messaged you first. To initiate a conversation, use a template message (Step 5).
    </Note>
  </Step>

  <Step title="Check the response">
    A successful request returns HTTP `200` with a JSON body confirming the message was accepted by WhatsApp:

    ```json theme={null}
    {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "917089379345",
          "wa_id": "917089379345"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgM..."
        }
      ]
    }
    ```

    The `messages[0].id` field is the WhatsApp message ID (`wamid`). You can use this ID to correlate delivery and read receipts that arrive via [webhooks](/guides/webhook-setup). If you receive a `4xx` response instead, double-check your API password and project ID.
  </Step>

  <Step title="Send a template message">
    To message a user who hasn't contacted you first — or outside the 24-hour service window — you must use a **pre-approved Message Template**. Templates are created and submitted for approval inside the Convo dashboard under **Templates**.

    Once your template is approved, send it like this:

    ```bash theme={null}
    curl -X POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages \
      -H "Content-Type: application/json" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -d '{
        "to": "917089379345",
        "type": "template",
        "template": {
          "name": "sample_shipping_confirmation",
          "language": {"policy": "deterministic", "code": "en_us"},
          "components": [
            {
              "type": "body",
              "parameters": [
                {"type": "text", "text": "6-7 days"}
              ]
            }
          ]
        }
      }'
    ```

    | Field                    | Description                                                   |
    | ------------------------ | ------------------------------------------------------------- |
    | `template.name`          | The exact name of your approved template.                     |
    | `template.language.code` | Language code of the template (e.g. `en_us`, `hi`, `es`).     |
    | `components`             | Array of component objects supplying dynamic variable values. |

    See the [Template Messages guide](/guides/template-messages) for a full breakdown of header, body, button, and media components.
  </Step>
</Steps>

## What's Next?

You've sent your first WhatsApp message via the Convo API. Here are the natural next steps:

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/concepts/business-and-projects">
    Understand Businesses, Projects, Contacts, and how they relate to each other.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore every available endpoint with full parameter and response documentation.
  </Card>

  <Card title="Send Templates" icon="file-lines" href="/guides/template-messages">
    Learn how to build rich template messages with images, buttons, and variables.
  </Card>

  <Card title="Set Up Webhooks" icon="webhook" href="/guides/webhook-setup">
    Receive real-time delivery receipts, read events, and inbound message payloads.
  </Card>
</CardGroup>