Atribuir um número a uma campanha de mensagens

Atribuir um número de envio a uma campanha

Utilize esta operação depois de a sua marca de mensagens e a sua campanha de produção estarem registadas e de a campanha estar ativa. Associa um número com SMS ativado da sua conta à campanha. Não cria uma marca, não cria nem aprova uma campanha, não compra um número nem envia uma mensagem.

O portal atual utiliza esta rota ao atribuir uma campanha a um número. A API pública aceita um identificador de campanha; deriva a marca a partir da campanha pertencente à conta, em vez de aceitar um identificador de marca separado.

Pedido

Envie um POST codificado como formulário através de HTTPS, utilizando a sua conta de API ativada e o respetivo endereço IP de origem permitido. Utilize os identificadores reais de número e de campanha da sua conta. O número neste exemplo é fictício.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Parâmetros de atribuição de campanha
Parâmetro	Obrigatório	Significado
action	Sim	Utilize add para atribuir ou delete para remover a associação de campanha atual do número. As maiúsculas/minúsculas e os espaços envolventes são normalizados.
campaign	Para add	O campaignId de uma campanha ACTIVE pertencente à conta autenticada. A respetiva marca também tem de pertencer à conta. Uma campanha explicitamente marcada como sandbox não pode ser atribuída a números de envio reais. Omita este parâmetro para delete; a remoção utiliza a associação existente do número.
number	Sim	O número de envio próprio, ativo, não anulado e com SMS ativado. Para um número norte-americano, utilize o código de país 1 seguido dos seus dez dígitos, sem sinal de mais. O handler remove os caracteres que não são dígitos e também procura os equivalentes com prefixo de mais e de dez dígitos. Esta normalização não é uma verificação geral de validade de números de telefone.

A operação altera um único número. Não tem paginação, parâmetro de lote nem opção de simulação (dry-run). Não utilize um endpoint de criação de campanhas apenas para associar um número a uma campanha existente.

Remover a associação atual

Utilize action=delete com o número próprio. Isto remove a associação do número com a campanha de envio e limpa os campos de marca/campanha guardados para esse número. Não elimina a campanha nem a marca, não liberta o número de telefone, não cancela o serviço do número nem interrompe a faturação recorrente da campanha.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Resposta e verificação

Este exemplo fictício ilustra o envelope de resposta habitual da API e alguns campos de resultado selecionados. O número devolvido preserva o formato guardado na sua conta. brandId e campaignId são cadeias vazias após uma remoção bem-sucedida.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus é o estado HTTP do parceiro de mensagens. O handler aceita uma resposta de transporte 2xx e, em seguida, atualiza o registo local do número; não interpreta o corpo da resposta do parceiro para obter um resultado de aceitação separado ao nível comercial. Por isso, uma resposta de sucesso não é prova de que o registo de mensagens está concluído nem de que a entrega será bem-sucedida. Reveja o estado da campanha do número no portal antes de enviar tráfego de produção.

Não considere uma associação local, por si só, como aprovação de entrega. A aprovação da campanha e da marca, o aprovisionamento do número, as permissões da conta, as regras de conteúdo e os limites habituais de mensagens continuam a aplicar-se.

Erros e resultados parciais

401: nenhuma conta autenticada está disponível para o handler.
400: action ou number está em falta ou é inválido, ou um pedido add não tem identificador de campanha.
404: o número não é um número de SMS próprio, ativo e não anulado.
409: a campanha não está disponível para a conta, não está ACTIVE, está explicitamente em sandbox ou a respetiva marca não está disponível para a conta.
503: a integração de mensagens não está disponível. Contacte o suporte em vez de alterar as credenciais da conta ou de inventar valores de configuração.
502: o pedido de mensagens falhou, excedeu o tempo limite ou devolveu um estado HTTP diferente de 2xx. providerStatus pode ser devolvido. Um tempo limite excedido não prova que o parceiro não fez nenhuma alteração.
500 com partial=true: o parceiro de mensagens devolveu um estado HTTP de sucesso, mas não foi possível confirmar a associação local. Reconcilie o número no portal ou contacte o suporte antes de tentar novamente.

Verifique o código de estado da API e o corpo da resposta, bem como o resultado HTTP. Não repita cegamente um pedido após um tempo limite excedido ou um resultado parcial. Este handler não tem chave de idempotência ao nível do pedido, reversão transacional nem verificação de conclusão do registo da campanha. Uma atribuição local repetida e idêntica pode devolver sucesso mesmo quando a base de dados não reporta linhas alteradas.

Âmbito e efeitos

Esta operação altera o encaminhamento do número de envio e a respetiva associação de campanha/marca guardada. No handler revisto, não contém nenhum débito direto na conta, criação de campanha, compra nem envio de mensagem. Isto não é um orçamento de preço nem uma promessa de serviço gratuito: os encargos existentes de número, campanha e mensagens continuam nos termos da sua conta.

No portal, mudar para uma campanha diferente remove primeiro a associação anterior e só depois adiciona a nova. São pedidos separados. Se o segundo pedido falhar, a associação anterior pode já ter sido removida. Não assuma que os dois pedidos são revertidos em conjunto.