Enviar SMS e MMS compatíveis

Antes de enviar

Envie um SMS ou um MMS compatível usando um número de envio configurado para a sua conta. Esta é uma operação em produção que pode contatar destinatários e gerar cobranças. Use apenas destinatários autorizados e tráfego aprovado; os números e a referência do exemplo abaixo são fictícios.

A sua conta precisa de aprovação para o envio de mensagens e das permissões aplicáveis ao remetente, ao país e ao tráfego. As credenciais diretas de usuários pessoais ou consumidores não são elegíveis para esta API. As credenciais dedicadas de API aprovadas seguem um processo de elegibilidade separado; remetentes móveis P2P podem exigir permissões adicionais de P2P e para os Estados Unidos e o Canadá. Confirme com a MultiTEL a configuração correta da conta, em vez de considerar uma credencial de API como permissão automática para enviar qualquer tráfego.

Solicitação de envio

Autentique-se por HTTPS com uma conta de API habilitada, a partir do endereço IP de origem permitido para ela. Mantenha as credenciais em um armazenamento de segredos no servidor. Use POST com campos codificados como formulário, ou um objeto JSON quando não forem fornecidos campos de formulário nem parâmetros de consulta. Não coloque credenciais nem o texto da mensagem em uma URL.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

Para um array JSON, use um array real em to; não coloque uma string que represente um array JSON dentro de um campo de formulário. Use o envio a um único destinatário como teste inicial de integração. O suporte a grupos e a MMS varia conforme a rota, portanto confirme a combinação compatível antes de usá-los.

Leia o resultado completo

Apenas alguns campos selecionados para ilustração; o custo exibido não é uma cotação.

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

Verifique em conjunto o status HTTP, status.code no JSON e status/message da resposta. Os códigos de resultado podem ser strings. Guarde sms_log_id_ori e os valores de mensagem e referência retornados para permitir a correlação pelo suporte. Os valores legados de uniqueid e pid variam conforme a rota; não deduza o formato deles nem presuma que sejam tokens de idempotência do cliente.

Success ou Message queued normalmente indica a aceitação pela rota selecionada, e não o recebimento no celular de uma pessoa. Um status de callback inicial como sent não comprova, por si só, a entrega final.

Segmentos e cobranças

Use Análise do comprimento de SMS no texto final completo antes do envio. Os preços de SMS dependem do destino e do serviço da conta; as taxas de operadora aplicáveis são adicionadas por segmento. O fluxo de envio combina os preços dos destinatários e as taxas aplicáveis e, em seguida, multiplica pela quantidade calculada de segmentos de SMS. Para esse cálculo, uma solicitação de MMS é tratada como uma mensagem.

cost e permsg são strings monetárias formatadas na resposta legada. carrier_fee_usd informa a parcela correspondente à taxa da operadora em USD e já está incluída no total calculado do envio; não a adicione uma segunda vez. É necessário verificar os preços efetivos e a disponibilidade de rotas para a sua conta. A solicitação não é uma operação apenas de consulta de preço.

O código revisado efetua o débito após a conclusão bem-sucedida do fluxo de envio pela operadora, mas a aceitação pela operadora, a persistência local e a cobrança não constituem uma única transação. Um erro ou o esgotamento do tempo limite pode ocorrer depois que uma solicitação já tiver sido aceita pelo serviço a montante. Nenhuma chave de idempotência do cliente é disponibilizada: repetir a mesma referência pode gerar um novo envio e uma nova cobrança.

Entrega local e resultados mistos

Números hospedados localmente podem ser aceitos (accepted) no fluxo de recebimento de mensagens da MultiTEL sem envio por uma operadora externa. Para uma solicitação inteiramente local, a resposta pode incluir accepted, message_id, provider e delivery_status. A aceitação local não garante que o destino de encaminhamento configurado pelo destinatário tenha funcionado.

Examine local_delivery_results e partial quando estiverem presentes. Um destinatário pode apresentar accepted com valor true mesmo que o resultado do encaminhamento seja malsucedido. Uma solicitação mista pode ter destinatários aceitos (accepted) pela operadora e uma parte local com falha. Não reenvie o lote inteiro automaticamente: primeiro concilie o resultado de cada destinatário.

Neste fluxo, a aceitação inteiramente local informa custo de envio zero, mas os destinatários ainda podem estar sujeitos às cobranças normais de recebimento de mensagens. Não interprete um custo de envio zero como garantia de que nenhuma conta será cobrada.

Callbacks e correlação

Quando notifyurl é fornecido, o callback inicial contém um envelope status e campos de resposta que incluem message_id, reference, from, to, status, status_text, error_code, timestamp e accepted. Os resultados locais também podem estar presentes. Armazene as informações de correlação sem registrar em logs as credenciais de API nem conteúdo desnecessário das mensagens.

Este processador não adiciona um campo de assinatura a esse callback inicial. Não use um callback não verificado como autorização suficiente, por si só, para outra ação. Consulte a configuração de integração ou webhook compatível com a sua conta e concilie os resultados incertos com os registros do portal ou com o suporte. Não presuma que os callbacks cheguem uma única vez nem na ordem da entrega final.

Falhas e recuperação segura

Falhas de validação podem usar o código de API 403. Recusas relacionadas à aprovação da conta e às políticas de P2P e de país também podem definir HTTP 403 e incluir um response.code legível por máquina. Limites de taxa podem usar 429 com informações sobre uma nova tentativa. Uma política indisponível ou uma falha de envio ou de persistência local pode usar 503 ou 500; a resposta legada de saldo insuficiente também pode retornar 500.

Para 429, respeite Retry-After e qualquer valor de response.retry_after. Em caso de rejeição da conta, do remetente, do país ou do destinatário, corrija a causa antes de tentar novamente. Em caso de esgotamento do tempo limite ou de resultado de envio incerto, guarde o horário da solicitação, a referência e os identificadores retornados, consulte o portal e contate o suporte antes de reenviar. A ausência de um registro no log, por si só, não prova que nenhuma operadora aceitou a solicitação.