> For the complete documentation index, see [llms.txt](https://docs.smsfire.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfire.com.br/apis-v2/sms/enviar-mensagem.md).

# Enviar mensagem

Veja detalhes de como realizar o envio de uma ou mais mensagens.

A partir deste serviço você poderá enviar mensagens individuais ou em massa, agendar envios, fracionar lotes de envios e muito mais.

{% hint style="danger" %}
Fique atento quanto ao [rate-limit](/apis-v2/rate-limiter.md) de requisições para o correto funcionamento da API.
{% endhint %}

## Fluxo da mensagem

Hoje somos um gateway de mensageria com imenso [*know-how*](https://www.dicio.com.br/know-how/) sobre as tecnologias e tipos de roteamento do mundo SMS. Por isso, mantemos o máximo de conexões disponíveis com [brokers nacionais e internacionais](https://en.wikipedia.org/wiki/SMS_gateway) para conseguirmos manter excelente qualidade de serviço com níveis extremamente reduzidos de incidências.

Desta forma, ofereceremos tarifas abaixo da média do mercado com periodicidade de reajustes extremamente reduzida para clientes de pequeno e médio porte que não conseguem boas tarifas aliadas a boa qualidade de serviço e atendimento.

Com isso conseguimos realizar diversos *mixes* de conexões no tráfego de nossos clientes de acordo com o tipo de envio, sendo eles para fins de [marketing ](https://pt.wikipedia.org/wiki/Mobile_marketing)ou [OTP](https://en.wikipedia.org/wiki/One-time_password).

![](https://3760200292-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MfDVaPn6RDe_e3UKyqi%2F-MfF4ZmydCopu_VJuLfG%2F-MfFOIbm_5RjvBis1Jqo%2FDiagrama%20em%20branco.png?alt=media\&token=db97c6e3-d319-4eff-9fe4-a8cf811fec77)

## HTTP Simplificado

<mark style="color:blue;">`GET`</mark> `https://api-v2.smsfire.com.br/sms/send/individual`

A partir de algumas propriedades aplicadas diretamente na URL é possível o envio individual de uma mensagem ao seu destinatário.

**Atenção:** Campos com \* (asterisco) são obrigatórios

#### Query Parameters

| Name                                   | Type    | Description                                                                                                                                              |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| to<mark style="color:red;">\*</mark>   | string  | Telefone do destinatário em formato internacional                                                                                                        |
| text<mark style="color:red;">\*</mark> | string  | Texto da mensagem. (Max. 765 caracteres)                                                                                                                 |
| from                                   | string  | Remetente da mensagem (Max. 11 caracteres)                                                                                                               |
| customId                               | string  | Id único personalizado da mensagem (Max. 40 caracteres)                                                                                                  |
| campaignId                             | integer | Id da campanha que deseja vincular a mensagem                                                                                                            |
| flash                                  | boolean | <p><code>true</code> ou <code>false</code><br>Quando <code>true</code>, a mensagem enviada é do tipo <em>Classe 0</em></p>                               |
| allowReply                             | boolean | <p><code>true</code> ou <code>false</code><br>Quando <code>true</code>, se a mensagem enviada for respondida, ela será disponibilizada em seu Inbox.</p> |
| scheduleTime                           | string  | Data de agendamento da mensagem. (ISO8601)                                                                                                               |

#### Headers

| Name                                            | Type   | Description    |
| ----------------------------------------------- | ------ | -------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Basic \<token> |

{% tabs %}
{% tab title="200 Objeto JSON" %}

```scheme
{
  "campaignId": 392,
  "messages": [
    {
      "id": 497235,
      "customId": "fire001001",
      "statusCode": 0,
      "statusName": "PENDING"
    }
  ]
}
```

{% endtab %}

{% tab title="400 Objeto JSON quando a requisição possuir algum dado inválido" %}

```scheme
{
  "error": {
    "message": "Invalid duplicated customId request"
  }
}
```

{% endtab %}
{% endtabs %}

> O parâmetro **`customId`** aceita caracteres alfanuméricos, hífen, underline/underscore e ponto sem espaços ou quebra de linha.

{% content-ref url="/pages/-MfGAplgQW3sbBmx3ZxL" %}
[Autenticação](/apis-v2/autenticacao.md)
{% endcontent-ref %}

### Exemplo de requisição

* Envio com parâmetros mínimos

`GET https://api-v2.smsfire.com.br/sms/send/individual?to=5511944556677&text=Ola`

* Envio com todos os parâmetros

`GET https://api-v2.smsfire.com.br/sms/send/individual?to=5511944556677&text=Ola&from=SMSFIRE&allowReply=true&flash=true&campaignId=0001&scheduleTime=2021-12-25T10:00:00`

> Para o correto funcionamento é imprescindível realizar o *encoding* da URL para que não haja distorções no conteúdo da mensagem.

## REST (JSON)

<mark style="color:green;">`POST`</mark> `https://api-v2.smsfire.com.br/sms/send/bulk`

Realize envios a múltiplos destinatários numa única requisição de forma personalizada para cada um dos números.

**Atenção:** Campos com \* (asterisco) são obrigatórios

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Basic \<Token>   |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                   | Type    | Description                                                  |
| ------------------------------------------------------ | ------- | ------------------------------------------------------------ |
| destinations<mark style="color:red;">\*</mark>         | array   | Matriz com a relação de destinatários.                       |
| destinations\[].to<mark style="color:red;">\*</mark>   | string  | Telefone do destinatário em formato internacional.           |
| destinations\[].text<mark style="color:red;">\*</mark> | string  | Texto da mensagem. (Max. 765 caracteres)                     |
| destinations\[].customId                               | string  | Id único personalizado. (Max 40 caracteres)                  |
| destinations\[].flash                                  | boolean | Enviar mensagem em *Classe 0*                                |
| campaignId                                             | integer | Id da campanha para vincular a mensagem.                     |
| allowReply                                             | boolean | Ativa o recebimento das respostas (MOs) no Inbox do usuário. |
| scheduleTime                                           | string  | Data do agendamento do envio. (ISO8601)                      |
| fractionate                                            | object  | Objeto responsável em criar o fracionamento dos envios       |
| fractionate.parts                                      | integer | Número de partes que o lote deverá ser dividido              |
| fractionate.interval                                   | integer | Tempo de espera - em minutos - entre as partes.              |

{% tabs %}
{% tab title="200 Array do objeto JSON" %}

```scheme
{
  "campaignId": 394,
  "messages": [
    {
      "id": 497237,
      "customId": "fire00001",
      "statusCode": 0,
      "statusName": "PENDING"
    },
    {
      "id": 497238,
      "customId": "fire00002",
      "statusCode": 0,
      "statusName": "PENDING"
    }
  ]
}
```

{% endtab %}

{% tab title="400 Objeto JSON quando a requisição possuir algum dado inválido" %}

```scheme
{
  "error": {
    "message": "Invalid duplicated customId request"
  }
}
```

{% endtab %}
{% endtabs %}

> O parâmetro **`customId`** aceita caracteres alfanuméricos, hífen, underline/underscore e ponto sem espaços ou quebra de linha.

{% hint style="info" %}
É possível enviar no máximo **100 destinatários** por requisição
{% endhint %}

{% content-ref url="/pages/-MfGAplgQW3sbBmx3ZxL" %}
[Autenticação](/apis-v2/autenticacao.md)
{% endcontent-ref %}

### Exemplos de requisição

* Exemplo simplificado de requisição com parâmetros mínimos obrigatórios:

{% tabs %}
{% tab title="curl" %}

```typescript
curl --request POST \
  --url https://api-v2.smsfire.com.br/sms/send/bulk \
  --header 'Authorization: Basic <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"destinations":[{"to":"5511944556677","text":"Mensagem teste 01"},{"to":"5511966778899","text":"Mensagem teste 02"}]}'
```

{% endtab %}

{% tab title="nodejs" %}

```javascript
var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://api-v2.smsfire.com.br/sms/send/bulk',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic <TOKEN>'
  },
  data: {destinations: [{to: '5511944556677', text:'Mensagem teste 01'}, {to: '551166778899', text:'Mensagem teste 02'}]}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "https://api-v2.smsfire.com.br/sms/send/bulk"

payload = {"destinations": [{"to": "5511944556677", "text":"Mensagem teste 01"}, {"to": "5511966778899", "text":"Mensagem teste 02"}]}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <TOKEN>"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

{% endtab %}

{% tab title="php" %}

```php
<?php

$curl = curl_init();
$payload = [
  "destinations" => [
    [
      "to" => "5511944556677",
      "text" => "Mensagem teste 01"
    ],
    [
      "to" => "5511966778899",
      "text" => "Mensagem teste 02"
    ]
  ]
];
    
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-v2.smsfire.com.br/sms/send/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <TOKEN>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

{% endtab %}
{% endtabs %}

* Exemplo de JSON com agendamento e id personalizado definido pelo cliente:

```typescript
{	
	"scheduleTime":"2021-12-25T10:00:00",
	"destinations":[
		{
			"to": "5511944556677",
			"text":"Mensagem teste 01",
			"customId":"fire00001",
			"from":"remetente01",
			"flash": true
		},
		{
			"to": "5511955667788",
			"text":"Mensagem teste 02",
			"customId":"fire00002",
			"from":"remetente02"
		}
	]
}
```

> O parâmetro `from` tem efetividade apenas a alguns países de destino. No caso do Brasil ele é apenas uma informação adicional, já que as operadoras sempre entregam a mensagem com um remetente numérico definido por elas mesmas.

* Exemplo de JSON com fracionamento de mensagem:
  * Na forma demonstrada, os `destinations` serão divididos em 2 lotes onde o primeiro será enviado imediatamente e o segundo será enviado após 10 minutos.

```typescript
{	
	"fractionate":{
		"parts":2,
		"interval":10
	},
	"destinations":[
		{
			"to": "5511944556677",
			"text":"Mensagem teste 01"
		},
		{
			"to": "5511966778899",
			"text":"Mensagem teste 02"
		}
	]
}
```

* Exemplo de JSON com agendamento e fracionamento de mensagem:
  * Na forma demonstrada, os `destinations` serão divididos em 2 lotes onde o primeiro será enviado na data descrita em `scheduleTime` e o segundo será enviado 10 minutos após.

```typescript
{	
	"scheduleTime":"2021-12-25T10:00:00",
	"fractionate":{
		"parts":2,
		"interval":10
	},
	"destinations":[
		{
			"to": "5511944556677",
			"text":"Mensagem teste 01"
		},
		{
			"to": "5511966778899",
			"text":"Mensagem teste 02"
		}
	]
}
```

* Exemplo de JSON permitindo a captação de respostas:

```typescript
{	
	"allowReply":true,
	"destinations":[
		{
			"to": "5511944556677",
			"text":"Mensagem teste 01"
		},
		{
			"to": "5511966778899",
			"text":"Mensagem teste 02"
		}
	]
}
```

## Informações adicionais

Destacamos a importância da leitura das seções apresentadas abaixo. Nessas seções você terá o detalhamento sobre caracteres acentuados e especiais, concatenação de mensagem, fracionamento de lote, agendamento e possíveis códigos  HTTP que a nossa API poderá gerar em situações de erro da requisição ou interno.

{% content-ref url="/pages/-MfEr5pjXMTYcgGHwVS-" %}
[Caracteres e concatenação](/apis-v2/sms/caracteres-concatencao.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MfEzRmFD5-lKWPDti3f" %}
[Fracionador de envios](/apis-v2/sms/fracionador-de-envios.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MfEz\_Y6-LJoe5S\_O-m9" %}
[Agendamento de mensagens](/apis-v2/sms/agendamento-de-mensagens.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MfFn9OJQjMoOeO65xfY" %}
[Código de status](/apis-v2/sms/codigo-de-status.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MfEpioeTXg1RKyz6SG9" %}
[HTTP CODES](/apis-v2/http-codes.md)
{% endcontent-ref %}
