Skip to main content
Convo authenticates all API requests via a single HTTP request header. There are no cookies, no OAuth flows, and no query-string tokens. Every request to the Convo API must include the X-API-WA-Project-API-Pwd header, or the server will respond with 401 Unauthorized.

​
Project API Password

Header: X-API-WA-Project-API-Pwd The Project API Password is scoped to a single Convo project (and its associated WhatsApp number). It is used for all API operations, including sending messages, managing contacts, and triggering campaigns.

​
How to obtain it

  1. Log in to the Convo Dashboard.
  2. Navigate to Settings → API & Integrations.
  3. Copy the value labelled Project API Password.
This password is set once per project and remains valid until you regenerate it. Regenerating it will immediately invalidate the previous value, so update all your integrations if you rotate it.

​
Example request

Replace {project_id} with your project’s ID and YOUR_API_PASSWORD with the password you copied from the dashboard.

​
Security Best Practices

API credentials give full programmatic access to your Convo account. Treat them with the same care as passwords.
  • Never expose keys in client-side code. Do not embed the API password in browser JavaScript, mobile app binaries, or public repositories. Anyone who obtains your key can send messages on your behalf.
  • Use environment variables. Store credentials in environment variables (e.g. CONVO_API_PASSWORD) and read them at runtime. This keeps secrets out of your codebase entirely.
  • Use a secrets manager in production. For production workloads, store credentials in a dedicated secrets manager such as AWS Secrets Manager, HashiCorp Vault, or GCP Secret Manager, and inject them into your application at startup.
  • Rotate keys if compromised. If you believe a key has been exposed, regenerate it immediately from the Convo dashboard and update all affected integrations.
Never hard-code API keys directly in your source code. If your repository is ever made public — intentionally or accidentally — exposed credentials can be exploited immediately. Always use environment variables or a secrets manager to inject credentials at runtime.

​
Error Responses

When authentication fails or a request is malformed, Convo returns a standard HTTP error status code alongside a JSON body describing the problem.

​
Example error response

The response body follows a consistent structure with name and message fields:
Use the name field for programmatic error handling in your code, and the message field to understand what specifically went wrong. For 401 errors, verify that you are sending the correct header name and that the credential value has not expired or been regenerated.