# Enviar e pedir localização

> Envie um ponto no mapa ou peça ao contato que compartilhe a localização dele no WhatsApp.

Duas tarefas de localização, ambas só no WhatsApp: enviar um ponto no mapa e pedir a localização do contato. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns).

## Enviar uma localização

Use `type: "location"` em `POST /v1/messages`.

| Campo | Regra |
| --- | --- |
| `location.latitude` | Número de -90 a 90 |
| `location.longitude` | Número de -180 a 180 |
| `location.name` | Opcional, até 256 caracteres |
| `location.address` | Opcional, até 512 caracteres |

  **cURL**

```bash
curl -X POST https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "location",
  "location": {
    "latitude": -23.5614,
    "longitude": -46.6559,
    "name": "Loja Paulista",
    "address": "Av. Paulista, 1000, São Paulo"
  }
}'
```

  **TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const message = await messajo.messages.send({
  connection_id: "con_123",
  to: "5511999990000",
  type: "location",
  location: {
    latitude: -23.5614,
    longitude: -46.6559,
    name: "Loja Paulista",
    address: "Av. Paulista, 1000, São Paulo",
  },
});
console.log(message.id, message.status);
```

  **n8n**
n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "location",
  "location": {
    "latitude": -23.5614,
    "longitude": -46.6559,
    "name": "Loja Paulista",
    "address": "Av. Paulista, 1000, São Paulo"
  }
}
```

A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook.

## Pedir a localização do contato

Use `type: "interactive"` com `interactive.type: "location_request_message"`. O contato vê o texto e um botão para compartilhar a localização. `body.text` tem até 1024 caracteres e `action.name` é sempre `send_location`.

  **cURL**

```bash
curl -X POST https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": { "text": "Para onde enviamos o pedido?" },
    "action": { "name": "send_location" }
  }
}'
```

  **TypeScript**

```ts
await messajo.messages.send({
  connection_id: "con_123",
  to: "5511999990000",
  type: "interactive",
  interactive: {
    type: "location_request_message",
    body: { text: "Para onde enviamos o pedido?" },
    action: { name: "send_location" },
  },
});
```

  **n8n**
n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "con_123",
  "to": "5511999990000",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": { "text": "Para onde enviamos o pedido?" },
    "action": { "name": "send_location" }
  }
}
```

### Receber a resposta

Quando o contato compartilha a localização, chega um evento [`message.received`](/webhooks/events/) com `content.type: "location"`:

```json
{
  "type": "location",
  "latitude": -23.5614,
  "longitude": -46.6559,
  "name": null,
  "address": null,
  "url": null
}
```

`name`, `address` e `url` vêm `null` quando o contato não os informa. Se ele ignorar o pedido, nada chega.

## Instagram e Messenger

Não aceitam `location` nem `interactive`: devolvem `422 type_not_supported_by_channel`.

## Erros

| Código | Status | Quando |
| --- | --- | --- |
| `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h |
| `validation_failed` | 400 | Latitude ou longitude fora da faixa, ou texto acima do limite |
| `type_not_supported_by_channel` | 422 | Instagram ou Messenger |
