WhatsApp messages

The whatsapp module sends text messages through the Evolution API (/message/sendText/{instance}). It is a thin wrapper: one REST endpoint and a service using fetch.

Key points

• • Config via EVOLUTION_API_URL / INSTANCE / KEY
• • POST /whatsapp/send with JWT
• • Phone number sent as provided
• • Network/API failures propagate as HTTP 502
• • WhatsappService exported

whatsapp namespace in src/config/whatsapp.config.ts:

EVOLUTION_API_URL=http://localhost:8080
EVOLUTION_API_INSTANCE=default
EVOLUTION_API_KEY=your-api-key

Instance

The instance must exist in Evolution API. The key is sent as the apiKey request header. Missing URL/instance yields HTTP 503.

Main method:

• • sendMessage(to, message) — POST ${url}/message/sendText/${instance}
• • Body: { number: to, text: message }
• • Headers: Content-Type application/json, apiKey

Error behavior

Network or non-OK Evolution HTTP → BadGatewayException (502). Missing config → ServiceUnavailableException (503). The controller does not return 200 in those cases.

// WhatsappService.sendMessage(to, message)
// number is sent as-is

POST ${EVOLUTION_API_URL}/message/sendText/${EVOLUTION_API_INSTANCE}
Headers: { "Content-Type": "application/json", "apiKey": "..." }
Body: { "number": to, "text": message }

JWT required. No @Roles — any authenticated user.

DTO

• • to — digit-only string (@Matches /^\d+$/); sent as-is
• • message — non-empty string

Send message

to: digits only, in the format Evolution expects (include DDI yourself if needed, e.g. 5511999999999). message: text.

POST /api/v1/whatsapp/send
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "to": "5511999999999",
  "message": "Hello, this is a test message"
}

Success response

{
  "message": "WhatsApp message sent successfully"
}

Error responses

• • 401 — missing or invalid JWT
• • 502 — Evolution unreachable or returned an error
• • 503 — EVOLUTION_API_URL / INSTANCE not configured

Import WhatsappModule and inject WhatsappService.

@Module({
  imports: [WhatsappModule],
  providers: [MyService],
})
export class MyModule {}

@Injectable()
export class MyService {
  constructor(private readonly whatsappService: WhatsappService) {}

  async notify(phone: string, text: string) {
    await this.whatsappService.sendMessage(phone, text);
  }
}