Introdução

Base URL: https://api.shortcode.com.br

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Envio

Permite o envio de até 1000 mensagens por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "001",
    "number": "41999999999",
    "message": "Ola, esta e uma mensagem."
  }
]

Resposta de sucesso (201)

[
  {
    "external_id": "001",
    "number": "41999999999",
    "operadora": "CLARO",
    "status": "accepted"
  },
  {
    "external_id": "002",
    "number": "41988888888",
    "operadora": "invalido",
    "status": "failed",
    "reason": "Número com operadora inválida"
  }
]

Status disponíveis

• accepted – Envio aceito com sucesso
• failed – Envio não aceito (ver reason)

Erros comuns

• 400 – JSON inválido, campos obrigatórios ausentes ou limite excedido
• 401 – Token ausente ou IP não autorizado
• 402 – Saldo insuficiente
• 403 – Token inválido
• 404 – Usuário não encontrado
• 423 – Usuário bloqueado

Webhook: DLR

Notificação de entrega da mensagem.

{
  "dlrs": [
    {
      "date": "2021-07-14 08:00:07",
      "external_id": "1525",
      "number": "41992375284",
      "operadora": "VIVO",
      "id_status": 3,
      "status": "Entregue com confirmação",
      "message": "Envio de Teste 01"
    }
  ]
}

id_status possíveis

• 2 – Entregue sem confirmação
• 3 – Entregue com confirmação
• 4 – Celular indisponível
• 6 – Recusado pela operadora

Webhook: MO (Resposta do Cliente)

Notificação quando o cliente responde um SMS.

{
  "mos": [
    {
      "date": "2021-07-14 10:33:47",
      "external_id": "",
      "number": "41992375284",
      "operadora": "VIVO",
      "message": "Me liga por favor"
    }
  ]
}

Documentação da API RCS

Base URL: https://api.shortcode.com.br

Endpoint: POST /rcs/messages

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Informações Gerais

• Envie um array de mensagens no corpo (máx. 300 itens).
• numero: MSISDN com ou sem 55 (ex.: 5511999999999 ou 11999999999).
• agente_id: ID do agente RCS aprovado para o usuário.
• external_id: ID externo único por mensagem (evita duplicidade).
• fallback_sms: Mensagem alternativa enviada caso o RCS não esteja disponível. Se este campo não for definido, o sistema registrará a tentativa como falha em RCS e não realizará o envio.
• tipo: text | media | carousel | template.
• Envios com links/palavras sensíveis podem entrar em revisão interna.

Envio

Permite o envio de até 300 mensagens por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "rcs_001",
    "numero": "5511999999999",
    "agente_id": 7,
    "tipo": "text",
    "mensagem": "Olá! Tudo bem com você?",
    "fallback_sms": "Essa mensagem vai or SMS se não tiver RCS",
    "sugestoes": [
      { "type": "reply", "text": "Suporte", "id": "suporte_1" },
      { "type": "url",   "text": "Site",    "url": "https://shortcode.com.br" },
      { "type": "dial",  "text": "Central", "phone_number": "0800123456" }
    ]
  },
  {
    "external_id": "rcs_002",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "media",
    "media_url": "https://exemplo.com/imagem.jpg",
    "mensagem": "Confira nossa nova coleção!"
  },
  {
    "external_id": "rcs_003",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "carousel",
    "carousel": [
      {
        "title": "Produto 1",
        "text": "Descrição 1",
        "media": "https://exemplo.com/img1.jpg",
        "buttons": [ { "type": "url", "text": "Ver", "url": "https://produto1.com" } ]
      },
      {
        "title": "Produto 2",
        "text": "Descrição 2",
        "media": { "url": "https://exemplo.com/img2.jpg", "contentType": "image/jpeg" },
        "buttons": [
          { "type": "reply", "text": "Quero", "id": "quero_2" },
          { "type": "dial", "text": "Ligar", "phone_number": "0800123456" }
        ]
      }
    ]
  }
]

Resposta de sucesso (201)

[
  {
    "external_id": "rcs_001",
    "numero": "5511999999999",
    "tipo": "text",
    "status": "accepted",
    "message_id": "rcs.9d6f9cba342...",
    "operadora": "Vivo"
  },
  {
    "external_id": "rcs_002",
    "numero": "11999999999",
    "tipo": "media",
    "status": "accepted",
    "message_id": "rcs.1a2b3c4d5e...",
    "operadora": "Claro"
  },
  {
    "external_id": "rcs_003",
    "numero": "11999999999",
    "tipo": "carousel",
    "status": "accepted",
    "message_id": "rcs.abc123def45...",
    "operadora": "TIM"
  }
]

Erros Comuns

• 400 – JSON inválido, campos obrigatórios ausentes ou limite excedido
• 401 – Token ausente ou IP não autorizado
• 403 – Agente/Token inválido ou não autorizado
• 404 – Número/Usuário não encontrado
• 409 – external_id já utilizado
• 422 – Erro de validação (ex.: mídia sem URL http/https, mais de 4 botões, card sem conteúdo, carrossel fora do limite 1–10, etc.)

Sugestões (botões)

Sugestões podem ser enviadas como sugestoes (globais) para qualquer tipo ou dentro de cada card do carousel.

[
  {
    "external_id": "rcs_txt_btn",
    "numero": "5511999999999",
    "agente_id": 7,
    "tipo": "text",
    "mensagem": "Como podemos ajudar?",
    "sugestoes": [
      { "type": "reply", "text": "Suporte", "id": "suporte_1" },
      { "type": "url", "text": "Site", "url": "https://shortcode.com.br" },
      { "type": "dial", "text": "Central", "phone_number": "0800123456" }
    ]
  }
]

Carrossel (tipo: carousel)

Envie carousel como array de cards. Cada card deve ter ao menos um dos campos: title, text ou media.

• Quantidade de cards: 1 a 10.
• media pode ser string URL http/https ou objeto { "url": "..." , "contentType": "..." }.
• Botões por card: máximo 4 (tipos: url, dial, reply).

[
  {
    "external_id": "rcs_car001",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "carousel",
    "carousel": [
      {
        "title": "Produto 1",
        "text": "Descrição 1",
        "media": "https://exemplo.com/img1.jpg",
        "buttons": [ { "type": "url", "text": "Ver", "url": "https://produto1.com" } ]
      },
      {
        "title": "Produto 2",
        "text": "Descrição 2",
        "media": { "url": "https://exemplo.com/img2.jpg", "contentType": "image/jpeg" },
        "buttons": [ { "type": "reply", "text": "Quero", "id": "quero_2" }, { "type": "dial", "text": "Ligar", "phone_number": "0800123456" } ]
      }
    ],
    "sugestoes": [ { "type": "reply", "text": "Falar com atendente", "id": "atd" } ]
  }
]

Webhooks RCS

Cadastre URLs para receber atualizações de mensagens recebidas e relatórios de entrega.

{
  "messages_received": [
    {
      "message_id": "rcs.9d6f9cba342...",
      "date": "2025-07-08 14:32:00",
      "external_id": "",
      "numero": "5511999999999",
      "mensagem": "Oi, quero saber mais!",
      "tipo": "text",
      "media_url": null
    }
  ]
}

{
  "messages_received": [
    {
      "message_id": "rcs.a0fe5415-2fc4...",
      "date": "2025-07-08 14:32:00",
      "external_id": "",
      "numero": "5511999999999",
      "mensagem": "video_cliente.mp4",
      "tipo": "media",
      "media_url": "https://rcs-copper-us.googleapis.com/blob/...",
      "mime_type": "video/mp4",
      "file_name": "video_cliente.mp4"
    }
  ]
}

{
  "delivery_reports": [
    {
      "message_id": "rcs.9d6f9cba342...",
      "date": "2025-07-08 14:32:00",
      "external_id": "rcs_car001",
      "numero": "5511999999999",
      "operadora": "Vivo",
      "tipo": "carousel",
      "tipo_envio": "single",
      "id_status": 22,
      "status": "lido"
    }
  ]
}

{
  "rcs_click": [
    {
      "date": "2025-07-08 14:32:00",
      "external_id": "rcs_car001",
      "numero": "5511999999999",
      "agente_id": 15,
      "click_button": "Quero"
    }
  ]
}

Documentação da API WhatsApp Business (WABA)

Base URL: https://api.shortcode.com.br

Endpoint: POST /whatsapp/messages

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Informações Gerais

• Envie até 300 mensagens por requisição
• canal_id: ID do canal WhatsApp configurado para o usuário
• external_id: Identificador único da mensagem
• number: Número do destinatário (10 a 15 dígitos)
• type: text | template | image | audio | video | document | sticker | location | contact | button | list
• fallback_sms (opcional): Mensagem alternativa via SMS se WhatsApp falhar
• Templates requerem aprovação prévia do Meta
• Mensagens fora de template exigem janela de 24h

Envio de Mensagens

Envio de mensagens pelo WhatsApp Business API oficial.

Exemplo: Mensagem de Texto com Fallback

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "text",
    "message": "Olá! Como posso ajudar?",
    "fallback_sms": "Olá! Como posso ajudar? (via SMS)"
  }
]

Exemplo: Mensagem de Texto (sem Fallback)

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "text",
    "message": "Olá! Como posso ajudar?"
  }
]

Exemplo: Template com Fallback

[
  {
    "external_id": "msg002",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "template",
    "fallback_sms": "Olá João Silva, seu pedido está confirmado!",
    "template": {
      "name": "boas_vindas",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "text": "João Silva" }
          ]
        }
      ]
    }
  }
]

Exemplo: Imagem

[
  {
    "external_id": "msg003",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "image",
    "media_url": "https://exemplo.com/imagem.jpg",
    "mimetype": "image/jpeg",
    "caption": "Confira nossa promoção!"
  }
]

Resposta de sucesso (201)

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "type": "text",
    "status": "accepted",
    "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg..."
  }
]

Tipos de Mensagens

1) text — Texto simples

{
  "type": "text",
  "message": "Sua mensagem aqui",
  "fallback_sms": "Mensagem alternativa via SMS (opcional)"
}

2) template — Template aprovado

{
  "type": "template",
  "fallback_sms": "Texto alternativo se WhatsApp falhar (opcional)",
  "template": {
    "name": "nome_do_template",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "URL_IMAGEM" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "text": "Variável 1" },
          { "text": "Variável 2" }
        ]
      },
      {
        "type": "button",
        "index": 0,
        "parameters": [
          { "text": "Código123" }
        ]
      }
    ]
  }
}

3) image — Imagem

{
  "type": "image",
  "media_url": "https://exemplo.com/foto.jpg",
  "mimetype": "image/jpeg",
  "caption": "Legenda opcional"
}

4) video — Vídeo

{
  "type": "video",
  "media_url": "https://exemplo.com/video.mp4",
  "mimetype": "video/mp4",
  "caption": "Assista agora!"
}

5) audio — Áudio

{
  "type": "audio",
  "media_url": "https://exemplo.com/audio.mp3",
  "mimetype": "audio/mpeg"
}

6) document — Documento

{
  "type": "document",
  "media_url": "https://exemplo.com/arquivo.pdf",
  "mimetype": "application/pdf",
  "caption": "Contrato anexo"
}

7) button — Botões interativos

{
  "type": "button",
  "interactive": {
    "body": "Escolha uma opção:",
    "buttons": [
      { "id": "btn1", "title": "Opção 1" },
      { "id": "btn2", "title": "Opção 2" },
      { "id": "btn3", "title": "Opção 3" }
    ]
  }
}

8) list — Lista interativa

{
  "type": "list",
  "interactive": {
    "header": "Menu Principal",
    "body": "Selecione uma categoria:",
    "footer": "Atendimento 24h",
    "button": "Ver opções",
    "sections": [
      {
        "title": "Produtos",
        "rows": [
          { "id": "prod1", "title": "Produto A", "description": "Descrição A" },
          { "id": "prod2", "title": "Produto B", "description": "Descrição B" }
        ]
      }
    ]
  }
}

Templates com Variáveis

Templates devem ser previamente aprovados pelo Meta e cadastrados no sistema.

Estrutura de components

• header – Cabeçalho com texto ou mídia
• body – Corpo da mensagem com variáveis
• button – Botões dinâmicos (com index)

Exemplo completo

{
  "type": "template",
  "template": {
    "name": "confirmacao_pedido",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "https://exemplo.com/logo.jpg" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "text": "João" },
          { "text": "12345" },
          { "text": "R$ 150,00" }
        ]
      },
      {
        "type": "button",
        "index": 0,
        "parameters": [
          { "text": "https://loja.com/pedido/12345" }
        ]
      }
    ]
  }
}

Fallback SMS

Configure uma mensagem alternativa para ser enviada via SMS caso o envio via WhatsApp falhe.

Exemplo com fallback

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "template",
    "template": {
      "name": "boas_vindas",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "text": "João Silva" }
          ]
        }
      ]
    },
    "fallback_sms": "Olá João Silva, bem-vindo ao nosso sistema!"
  }
]

Como funciona

• 1) Sistema tenta enviar via WhatsApp
• 2) Se falhar (número sem WhatsApp, erro de envio, etc.)
• 3) Envia automaticamente via SMS usando o texto do fallback_sms
• Você recebe notificação do canal usado (WhatsApp ou SMS)

Janela de Conversação (24 horas)

Mensagens fora de template só podem ser enviadas dentro de 24 horas após a última mensagem recebida do cliente.

• Dentro da janela: qualquer tipo de mensagem
• Fora da janela: apenas templates aprovados
• A janela reinicia a cada mensagem recebida

Webhooks WhatsApp

Você pode cadastrar URLs para receber atualizações automáticas sobre mensagens enviadas ou recebidas.

{
  "messages_received": [
    {
      "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg...",
      "date": "2025-07-08 14:32:08",
      "external_id": "",
      "number": "5547991170182",
      "message": "Oi, quero saber mais!",
      "type": "text",
      "media_url": null
    }
  ]
}

{
  "delivery_reports": [
    {
      "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg...",
      "date": "2025-07-08 14:32:08",
      "external_id": "mh-0001",
      "number": "5541999999999",
      "type": "text",
      "status": "delivered"
    }
  ]
}

Erros Comuns

• 400 – JSON inválido ou limite excedido
• 400 – Tipo de mensagem inválido
• 400 – Campos obrigatórios ausentes
• 400 – Canal não encontrado ou não pertence ao usuário
• 400 – Número inválido (deve ter 10-15 dígitos)
• 400 – Template não cadastrado
• 400 – Quantidade de variáveis incorreta
• 400 – Sem janela de conversação (use template)
• 400 – media_url ou mimetype ausente
• 401 – Token ausente ou inválido

Documentação da API VOZ

Base URL: https://api.shortcode.com.br

Endpoints:

• GET /voz/templates — Lista os templates de áudio disponíveis.
• POST /voz/messages — Envia mensagens de voz diretas ou por template.

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Templates

Retorna todos os templates de voz cadastrados para o usuário.

Resposta de sucesso (200)

{
  "templates": [
    {
      "id": 1,
      "nome": "Boas-vindas",
      "descricao": "Mensagem de boas-vindas automatizada",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_boas_vindas.mp3",
      "criado_em": "2025-10-23 10:40:12"
    },
    {
      "id": 2,
      "nome": "Aviso de promoção",
      "descricao": "Template de aviso promocional",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_promocao.mp3",
      "criado_em": "2025-10-21 14:30:44"
    }
  ]
}

Envio

Permite enviar até 300 mensagens de voz por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "voz_001",
    "numero": "5511999999999",
    "tipo": "audio",
    "audio_url": "https://app.shortcode.com.br/uploads/audio_teste.mp3"
  },
  {
    "external_id": "voz_002",
    "numero": "5511888888888",
    "tipo": "template",
    "id_template": 2
  }
]

Resposta de sucesso (201)

[
  {
    "external_id": "voz_001",
    "numero": "5511999999999",
    "status": "accepted",
    "message_id": "voz.82b9fbb7a4c9...",
    "operadora": "Vivo"
  },
  {
    "external_id": "voz_002",
    "numero": "5511888888888",
    "status": "accepted",
    "message_id": "voz.f7a2e9d0a31b...",
    "operadora": "Claro"
  }
]

Webhook: DLR (Relatório de Entrega)

Notificação automática enviada pelo sistema de voz quando ocorre mudança no status da chamada.

{
  "voz_delivery_report": [
    {
      "mensagem_id": "voz.8c3b4c9d1e2f",
      "external_id": "001",
      "numero": "5511999999999",
      "operadora": "Vivo",
      "id_status": 59,
      "status": "Atendida",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_boas_vindas.wav",
      "enviado_em": "2025-10-23 14:00:01",
      "entregue_em": "2025-10-23 14:00:09",
      "duracao_segundos": 8
    },
    {
      "mensagem_id": "voz.7a5f2c1d9b0e",
      "external_id": "voz_002",
      "numero": "5511888888888",
      "operadora": "Claro",
      "id_status": 58,
      "status": "Falha",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_cobranca.wav",
      "enviado_em": "2025-10-23 14:02:00",
      "entregue_em": "2025-10-23 14:02:00",
      "duracao_segundos": 0
    }
  ]
}

Erros comuns

• 400 – JSON inválido ou campos obrigatórios ausentes
• 401 – Token ausente ou IP não autorizado
• 403 – Usuário sem permissão VOZ
• 404 – Template não encontrado
• 422 – audio_url inválido (sem http/https)

Introdução

Base URL: https://api.shortcode.com.br

Authorization: Bearer SEU_TOKEN_AQUI

Tipos

• Link Encurtado – redireciona para uma URL
• WhatsApp – abre conversa com mensagem pré-definida
• Rotativo – distribui conversas entre múltiplos números

Listar

GET /links
GET /links?tipo=Whatsapp
GET /links?tipo=Rotativo

Criar

{
  "tipo": "link",
  "keyword": "promo2025",
  "url": "https://seusite.com/promocao-2025"
}

Webhook: cliques

{
  "clicks": [
    {
      "date": "2025-11-19 14:30:45",
      "external_id": "1525",
      "number": "5547991170182",
      "ip_address": "177.174.250.22",
      "click_type": "human"
    }
  ]
}