Introdução SDKs

A Comtele mantem oficialmente uma API REST, mas também criamos alguns EXEMPLOS de pacote SDK para auxiliar os desenvolvedores a criarem seus próprios códigos. Estas SDKs são open-source e tem o intuíto de servir como exemplos para os desenvolvedores. Incentivamos e orientamos que o uso de SDKs seja para que o desenvolvedor consiga criar seus próprios códigos e não para uso em versões finais de software, uma vez que os Exemplos de SDKs não são oficialmente suportados e nem mantidos atualizados com a última versão da API.

GitHub

Oficialmente nós damos suporte apenas para nossa API REST, mas também criamos alguns EXEMPLOS de SDK OpenSource que podem ser encontradas no GitHub pelos links: Python, .NET, .NET Core, Node, Java, Ruby, PHP via composer e importação de arquivos. Com isto, você pode montar seu próprio código/SDK se baseando em nossos exemplos e usando a linguagem de programação que desejar.

Autenticação

Todas as requisições direcionadas a qualquer recurso das SDKs devem ser autenticadas pela chave de integração que fica disponível em sua conta em https://sms.comtele.com.br em sua dashboard na secão Informações do Desenvolvedor nomeado como Sua Chave de API no seguinte formato: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Python

Instalação da SDK

comtele_sdk está disponível no PyPI o código é open source e pode ser encontrado em nosso GitHub github.com/comtele.

Apesar dos exemplos contidos nesta documentação serem realizados na versão 3, a versão mínima necessária do Python para instalar a SDK é a 2.7.16, caso esteja utilizando uma versão inferior recomendamos que utilize o Virtualenv, além disso, você pode dar uma olhadinha no nosso GitHub como fazer as chamadas via API Rest ou até então modificar os dependências que necessitam da versão mínima 2.7.16 e fazer a sua própria versão.

$ pip install comtele_sdk

Retorno de Sucesso da Instalação

Successfully built comtele_sdk
Installing collected packages: comtele_sdk
Successfully installed comtele_sdk

Enviar SMS

Com este recurso, é possivel enviar SMS de forma instantânea.

from comtele_sdk.textmessage_service import TextMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

textmessage_service = TextMessageService(api_key)
result = textmessage_service.send(
  'my_id',          # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'Hello Python',   # Content: Conteudo da mensagem a ser enviada.
  ['11999998888'])  # Receivers: Numero de telefone que vai ser enviado o SMS.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Regra de Resposta Automática

Com este recurso, é possivel enviar SMS de forma instantânea e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

from comtele_sdk.contextmessage_service import ContextMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contextmessage_service = ContextMessageService(api_key)
result = contextmessage_service.send(
  'my_id',            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'ContextRuleName',  # ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  ['11999998888'])    # Receivers: Numero de telefone que vai ser enviado o SMS.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Grupos de Contatos

Com este recurso, é possivel enviar SMS de forma instantânea para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

from comtele_sdk.contactmessage_service import ContactMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contactmessage_service = ContactMessageService(api_key)
result = contactmessage_service.send(
  'my_id',            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'Hello Python',     # Content: Conteudo da mensagem a ser enviada.
  'GroupName')        # GroupName: Nome do grupo de contatos que receberao o SMS

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados.

from comtele_sdk.textmessage_service import TextMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

textmessage_service = TextMessageService(api_key)
result = textmessage_service.schedule(
  'my_id',            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'Hello Python',     # Conteudo da mensagem a ser enviada.
  'yyyy-MM-dd HH:mm', # ScheduleDate: Data que o SMS deve ser disparado.
  ['11999998888'])    # Receivers: Numero de telefone que vai ser enviado o SMS.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS / Regra de Resposta Automática

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados, e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

from comtele_sdk.contextmessage_service import ContextMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contextmessage_service = ContextMessageService(api_key)
result = contextmessage_service.schedule(
  'my_id',            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'ContextRuleName',  # ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  'yyyy-MM-dd HH:mm', # ScheduleDate: Data que o SMS deve ser disparado.
  ['11999998888'])    # Receivers: Numero de telefone que vai ser enviado o SMS.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Agendar SMS / Grupos de Contatos

Com este recurso, é possivel programar a data e horário de envio de SMS para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

from comtele_sdk.contactmessage_service import ContactMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contactmessage_service = ContactMessageService(api_key)
result = contactmessage_service.schedule(
  'my_id',            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  'Hello Python',     # Conteudo da mensagem a ser enviada.
  'GroupName',        # GroupName: Nome do grupo de contatos que receberao o SMS.
  'yyyy-MM-dd HH:mm') # ScheduleDate: Data que o SMS deve ser disparado.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Enviar SMS / Dois Fatores

Com este recurso, é possivel enviar via SMS de forma instantânea um código de autenticação para o destinatário, que pode ser validado posteriormente no endpoint a seguir: Validar Código / Dois Fatores.

from comtele_sdk.token_service import TokenService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

token_service = TokenService(api_key)
result = token_service.send_token(
  '11999998888',  # PhoneNumber: Numero de telefone que vai ser enviado o token via SMS.
  'Company')      # Prefix: Identificação da empresa que aparecerá no corpo da mensagem.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": {
    "Prefix": "", 
    "PhoneNumber": ""
    }, 
  "Message": 
  "O token foi criado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Validar Código / Dois Fatores

Com este recurso, é possivel validar o token recebido e informado pelo usuário que recebeu o SMS, enviado pelo endpoint anterior anterior: Enviar SMS / Dois Fatores.

from comtele_sdk.token_service import TokenService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

token_service = TokenService(api_key)
result = token_service.validate_token(
  'TokenCode')  # TokenCode: Token que o cliente informou e deve ser validado pela Comtele.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": {
    "TokenCode": "XXXXXX"
    },
  "Message": "O token informado foi validado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Detalhado

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS enviados.
Este recurso possui um cooldown de 30 segundos que é compartilhando entre os recursos de Relatório de Regra de Resposta Automática, Relatório de Respostas e Histórico de Recargas, ou seja, somente uma chamada a cada 30 segundos a estes recursos podem ser realizadas.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@textmessage_service = TextMessageService.new(API_KEY)
result = @textmessage_service.get_detailed_report(
  "yyyy-MM-dd HH:mm", # StartDate: Data inicial a ser filtrado o relatorio.
  "yyyy-MM-dd HH:mm", # EndDate: Data final a ser filtrado o relatorio.
  DeliveryStatus.All) # DeliveryStatus.all, pode ser Delivered ou Undelivered.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": [
    {
      "Receiver": "", 
      "Content": "", 
      "Status": "", 
      "ScheduleDate": "", 
      "RequestDate": "", 
      "SystemMessage": "", 
      "DlrStatus": "", 
      "Sender": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Regra de resposta automática

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS enviados/recebidos utilizando a funcionalidade de regra de resposta automatica.
Este recurso possui um cooldown de 30 segundos que é compartilhando entre os recursos de Relatório Detalhado, Relatório de Respostas e Histórico de Recargas, ou seja, somente uma chamada a cada 30 segundos a estes recursos podem ser realizadas.

from comtele_sdk.contextmessage_service import ContextMessageService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contextmessage_service = ContextMessageService(api_key)
result = contextmessage_service.get_report(
  'yyyy-MM-dd HH:mm', # StartDate: Data inicial a ser filtrado o relatorio.
  'yyyy-MM-dd HH:mm', # EndDate: Data final a ser filtrado o relatorio.
  'ContextRuleName')  # ContextRuleName: Pode ser passado em branco caso nao queira filtrar a regra especifica que enviada.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object":  [
    {
      "Sender": "", 
      "Content": "", 
      "Received": "", 
      "ContextRuleName": "", 
      "StatusMessage": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Respostas

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS recebidos utilizando a funcionalidade de recebimento de respostas.
Este recurso possui um cooldown de 30 segundos que é compartilhando entre os recursos de Relatório Detalhado, Relatório de Regra de Resposta Automática e Histórico de Recargas, ou seja, somente uma chamada a cada 30 segundos a estes recursos podem ser realizadas.

from comtele_sdk.reply_service import ReplyService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

reply_service = ReplyService(api_key)
result = reply_service.get_report(
  'yyyy-MM-dd HH:mm', # StartDate: Data inicial a ser filtrado o relatorio.
  'yyyy-MM-dd HH:mm', # EndDate: Data final a ser filtrado o relatorio.
  'Sender')           # Sender: Pode ser passado em branco caso nao queira filtrar uma resposta. E o numero do telefone de quem ou o que respondeu o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Sender": "",
      "SentContent": "",
      "ReceivedContent": "",
      "ReceivedDate": "",
      "SenderName": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Receber Respostas / Callback

Com este recurso, é possivel receber ao invés de consultar todos os detalhes disponíveis dos SMS recebidos utilizando a funcionalidade de recebimento de respostas.

Configuração da URL

Antes de mais nada, para receber as respostas via callback, é necessário que você ja tenha construído em sua aplicação um webhook para receber a resposta no padrão a seguir, além disso é necessário que o endpoint do seu webhook seja público e que você tenha configurado em sua conta seguindo os seguintes passos:
1 - Acessar o painel em https://sms.comtele.com.br, e inserir os dados de acesso de sua conta.
2 - Na opção Configurações do menu lateral, clique em Alterar Meus Dados.
3 - Na tela de edição dos seus dados pessoais, localize a seção CONFIGURAÇÕES e a opção URL de Callback de Respostas, insira a URL do webhook que irá receber as respostas e clique no botão salvar.
Feito esses passos, em um intervalo máximo de 30 minutos, todas as respostas que estiverem atrelados aos SMS enviados pelo seu usuário serão retornados via callback.

Exemplo do objeto da resposta

  {
    "Sender":string,
    "SentContent":string,
    "ReceivedContent":string,
    "ReceiveDate":"yyyy-MM-ddThh:mm:ss.ms",
    "SenderName":string
  }

Campos do Retorno

Cadastrar / Grupos de Contatos

Com este recurso, é possivel cadastrar grupos de contatos para segmentar estes contatos em listas que podem ser usadas no momento do envio.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.create_group(
  'GroupName',    # GroupName: Nome do grupo a ser cadastrado.
  'Description')  # Description: Breve descricao do grupo a ser cadastrado.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Name": "group_name",
    "Description": "group_description"
  },
  "Message": "O grupo de contatos foi criado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar / Grupos de Contatos

Com este recurso, é possivel consultar os grupos de contatos cadastrados.

Consultar Todos os Grupos

Com este recurso, é possivel consultar detalhes de todos os grupos de contatos cadastrados em sua conta.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.get_all_groups()

print(result)

Consultar Grupo Específico

Com este recurso, é possivel consultar detalhes filtrando um grupo de contatos específico cadastrado em sua conta.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.get_group_name(
  'GroupName')  # GroupName: Nome do grupo a ser filtrado os detalhes.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Id": comtele_group_id,
      "Name": "group_name",
      "Description": "group_description",
      "TotalContacts": 1,
      "LastUsed": "yyyy-MM-dd HH:mm:ss.ms"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Excluir / Grupos de Contatos

Com este recurso, é possivel excluir grupos de contatos cadastrados.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.remove_group(
  'GroupName') # GroupName: Nome do grupo a ser excluido.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": null,
  "Message": "O grupo de contatos foi removido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Cadastrar Contatos / Grupos de Contatos

Com este recurso, é possivel cadastrar contatos em grupos para segmentar estes contatos em listas que podem ser usadas no momento do envio.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.add_contact_to_group(
  'GroupName',    # GroupName: Nome do grupo ja existente.
  '11999998888',  # ContactPhone: Numero de telefone do contato a ser cadastrado. 
  'ContactName')  # ContactName: Nome do contato a ser cadastrado, pode ser informado em branco.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "GroupName": "group_name",
    "Action": "add_number",
    "ContactPhone": "phone_number",
    "ContactName": "contact_name"
  },
  "Message": "O contato foi inserido no grupo com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Excluir Contatos / Grupos de Contatos

Com este recurso, é possivel remover contatos em grupos segmentados, para que estes contatos não recebam mais SMS destas listas quando usadas no momento do envio.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(api_key)
result = contact_service.remove_contact_from_group(
  'GroupName',    # GroupName: Nome do grupo que o contato esta cadastrado.
  '11999998888')  # ContactPhone: Numero de telefone do contato a ser excluido.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "GroupName": "group_name",
    "Action": "remove_number",
    "ContactPhone": "phone_number",
    "ContactName": "contact_name"
  },
  "Message": "O contato foi removido do grupo com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Cadastrar Contatos / Lista de Bloqueios

Com este recurso, é possivel adicionar números de telefone em uma Lista de Bloqueios para não receber mais SMS proveniente de sua conta, assim, você pode se despreocupar com uma verificação antes de mandar uma mensagem para números que não desejam mais receber seus SMS, basta adicionar estes telefones em sua blacklist, e caso seja enviado um SMS para este número, não será consumido crédito, o SMS não será entregue e aparecerá no relatório detalhado, uma mensagem informando que o número não recebeu o SMS pois está cadastrado na blacklist.

from comtele_sdk.blacklist_service import BlacklistService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

blacklist_service = BlacklistService(api_key)
result = blacklist_service.insert(
  '11999998888')  # PhoneNumber: Numero de telefone do contato a ser adicionado na Lista de Bloqueios.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "PhoneNumber": "",
    "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
  },
  "Message": "O numero foi inserido na Lista de Bloqueios com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Contatos / Lista de Bloqueios

Com este recurso, é possivel consultar os números de telefone e a data que foram adicionados na sua Lista de Bloqueios.

Consultar Todos Telefones

Com este recurso, é possivel consultar detalhes de todos os contatos cadastrados em sua Lista de Bloqueios.

from comtele_sdk.blacklist_service import BlacklistService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

blacklist_service = BlacklistService(api_key)
result = blacklist_service.get_blacklist()

print(result)

Consultar Telefone Específico

Com este recurso, é possivel consultar detalhes filtrando um contato específico cadastrado em sua Lista de Bloqueios.

from comtele_sdk.blacklist_service import BlacklistService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

blacklist_service = BlacklistService(api_key)
result = blacklist_service.get_by_phone_number(
  '11999998888')  # PhoneNumber: Numero de telefone do contato a ser consultado na Lista de Bloqueios.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "PhoneNumber": "phone_number",
      "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Excluir Contatos / Lista de Bloqueios

Com este recurso, é possivel remover números de telefone que foram adicionados na Lista de Bloqueios para voltar a receber os SMS provenientes de sua conta.

from comtele_sdk.blacklist_service import BlacklistService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

blacklist_service = BlacklistService(api_key)
result = blacklist_service.remove(
  '11999998888')  # PhoneNumber: Numero de telefone do contato a ser excluido na Lista de Bloqueios.

print(result)

Exemplo de Retorno de Sucesso

  {
    "Success": true,
    "Object": {
      "PhoneNumber": "",
      "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
    },
    "Message": "O numero foi removido da Lista de Bloqueios com sucesso."
  }

Campos do Retorno

Retornos Previsíveis

Consultar Saldo

Com este recurso, é possivel consultar a quantidade de saldo disponível em sua conta ou subcontas.

Consultar Saldo

Com este recurso, é possivel consultar saldo de sua conta.

from comtele_sdk.credit_service import CreditService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

credit_service = CreditService(api_key)
result = credit_service.get_my_credits()

print(result)

Consultar Saldo Subcontas

Com este recurso, é possivel consultar saldo de suas subconta.

from comtele_sdk.credit_service import CreditService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

credit_service = CreditService(api_key)
result = credit_service.get_credits(
  'Username') # Username: Username da subconta a ter o saldo consultado.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": 0,
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Inserir Saldo / Subcontas

Com este recurso, é possivel adicionar saldo em suas subcontas. Recurso disponível apenas para contas do tipo revenda

from comtele_sdk.credit_service import CreditService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

credit_service = CreditService(api_key)
result = credit_service.add_credits(
  'Username') # Username: Username da subconta a ter o credito inserido ou removido.
  'Amount')   # Amount: Quantidade de creditos a ser adicionada, o valor tambem pode ser negativo para remover o credito.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": null,
  "Message": "Os creditos foram alterados com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Histórico de Recargas / Subcontas

Com este recurso, é possivel consultar a histórico de créditos adicionados suas subcontas. Recurso disponível apenas para contas do tipo revenda

from comtele_sdk.credit_service import CreditService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

credit_service = CreditService(api_key)
result = credit_service.get_history(
  'Username') # Username: Username da subconta a ter o historico de recargas consultado.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Amount": 1,
      "Balance": 1,
      "ExpiryDate": null,
      "HistoryDate": "yyyy-MM-dd HH:mm.ms",
      "AssociadedUsername": "username"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Cadastrar / Subcontas

Com este recurso, é possivel cadastrar subcontas, se a sua conta for do tipo revenda. Dessa maneira é possível separar completamente a utilização das funcionalidades, créditos e acesso.

from comtele_sdk.account_service import AccountService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

account_service = AccountService(api_key)
result = account_service.create_account(
  'Comtele',              # Firstname: Primeiro nome da pessoa, ou nome da empresa a ser cadastrada.
  'test@comtele.com.br',  # Email: Email de contato do responsavel pela conta.
  '14121127000173',       # CorporateTaxpayer: CNPJ da empresa se for pessoa juridica.
  '00000000000',          # IndividualTaxpayer: CPF do responsavel se for pessoa fisica.
  '11999998888',          # MobileNumber: Numero de telefone do responsavel pela conta.
  'pass4w')               # Password: Senha da conta a ser cadastrada.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Enabled": true,
    "Username": "sub_account_username",
    "Balance": 0,
    "Connection": null,
    "LastBalanceHistory": null
  },
  "Message": "O usuario foi inserido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Consultar / Subcontas

Com este recurso, é possivel consultar as subcontas cadastradas e atreladas a sua conta.

Consultar Todos as Subcontas

Com este recurso, é possivel consultar detalhes de todas as subcontas cadastrados em sua conta.

from comtele_sdk.account_service import AccountService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

account_service = AccountService(api_key)
result = account_service.get_all_accounts()

print(result)

Consultar Subconta Específica

Com este recurso, é possivel consultar detalhe de uma subconta específica atrelada a sua conta.

from comtele_sdk.account_service import AccountService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

account_service = AccountService(api_key)
result = account_service.get_account_by_username(
  'Username') # Username: Username da subconta que deve ser consultado os detalhes cadastrais.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Enabled": true,
    "Username": "sub_account_username",
    "Balance": 0,
    "Connection": yyyy-MM-ddTHH:mm:ss.ms,
    "LastBalanceHistory": yyyy-MM-ddTHH:mm:ss.ms
  },
  "Message": "O usuario foi inserido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Ruby

Instalação da SDK

comtele_sdk está disponível no RubyGems o código é open source e pode ser encontrado em nosso GitHub github.com/comtele.

A versão mínima necessária do Ruby para instalar a SDK é a 2.0, caso esteja utilizando uma versão inferior recomendamos que utilize o RVM, além disso, você pode dar uma olhadinha no nosso GitHub como fazer as chamadas via API Rest ou até então modificar os dependências que precisam da versão 2.0 e fazer a sua própria versão.

$ gem install comtele_sdk

Retorno de Sucesso da Instalação

Done installing documentation for http-accept, unf_ext, unf, domain_name, http-cookie, mime-types-data, mime-types, netrc, rest-client, comtele_sdk after 8 seconds
10 gems installed

Enviar SMS

Com este recurso, é possivel enviar SMS de forma instantânea.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@textmessage_service = TextMessageService.new(API_KEY)
result = @textmessage_service.send(
  "my_id",          # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Ruby",     # Content: Conteudo da mensagem a ser enviada.
  ["11999998888"])  # Receivers: Numero de telefone que vai ser enviado o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Regra de Resposta Automática

Com este recurso, é possivel enviar SMS de forma instantânea e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contextmessage_service = ContextMessageService.new(API_KEY)
result = @contextmessage_service.send(
  "my_id",            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "ContextRuleName",  # ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  ["11999998888"])    # Receivers: Numero de telefone que vai ser enviado o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Grupos de Contatos

Com este recurso, é possivel enviar SMS de forma instantânea para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contactmessage_service = ContactMessageService.new(API_KEY)
result = @contactmessage_service.send(
  "my_id",            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Ruby",       # Content: Conteudo da mensagem a ser enviada.
  "GroupName")        # GroupName: Nome do grupo de contatos que receberao o SMS

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@textmessage_service = TextMessageService.new(API_KEY)
result = @textmessage_service.schedule(
  "my_id",            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Ruby",       # Content: Conteudo da mensagem a ser enviada.
  "yyyy-MM-dd HH:mm", # ScheduleDate: Data que o SMS deve ser disparado.
  ["11999998888"])    # Receivers: Numero de telefone que vai ser enviado o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS / Regra de Resposta Automática

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados, e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contextmessage_service = ContextMessageService.new(API_KEY)
result = @contextmessage_service.schedule(
  "my_id",            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "ContextRuleName",  # ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  "yyyy-MM-dd HH:mm", # ScheduleDate: Data que o SMS deve ser disparado.
  ["11999998888"])    # Receivers: Numero de telefone que vai ser enviado o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Agendar SMS / Grupos de Contatos

Com este recurso, é possivel programar a data e horário de envio de SMS para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contactmessage_service = ContactMessageService.new(API_KEY)
result = @contactmessage_service.schedule(
  "my_id",            # Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Ruby",     # Conteudo da mensagem a ser enviada.
  "GroupName",        # GroupName: Nome do grupo de contatos que receberao o SMS.
  "yyyy-MM-dd HH:mm") # ScheduleDate: Data que o SMS deve ser disparado.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Enviar SMS / Dois Fatores

Com este recurso, é possivel enviar via SMS de forma instantânea um código de autenticação para o destinatário, que pode ser validado posteriormente no endpoint a seguir: Validar Código / Dois Fatores.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@token_service = TokenService.new(API_KEY)
result = @token_service.send_token(
  "11999998888",  # PhoneNumber: Numero de telefone que vai ser enviado o token via SMS.
  "Company")      # Prefix: Identificação da empresa que aparecerá no corpo da mensagem.

print(result)

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": {
    "Prefix": "", 
    "PhoneNumber": ""
    }, 
  "Message": 
  "O token foi criado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Validar Código / Dois Fatores

Com este recurso, é possivel validar o token recebido e informado pelo usuário que recebeu o SMS, enviado pelo endpoint anterior anterior: Enviar SMS / Dois Fatores.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@token_service = TokenService.new(API_KEY)
result = @token_service.validate_token(
  "TokenCode")  # TokenCode: Token que o cliente informou e deve ser validado pela Comtele.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": {
    "TokenCode": "XXXXXX"
    },
  "Message": "O token informado foi validado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Detalhado

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS enviados.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@textmessage_service = TextMessageService.new(API_KEY)
result = @textmessage_service.get_detailed_report(
  "yyyy-MM-dd HH:mm", # StartDate: Data inicial a ser filtrado o relatorio.
  "yyyy-MM-dd HH:mm", # EndDate: Data final a ser filtrado o relatorio.
  DeliveryStatus::All) # DeliveryStatus::All, pode ser Delivered ou Undelivered.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": [
    {
      "Receiver": "", 
      "Content": "", 
      "Status": "", 
      "ScheduleDate": "", 
      "RequestDate": "", 
      "SystemMessage": "", 
      "DlrStatus": "", 
      "Sender": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Regra de resposta automática

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS enviados/recebidos utilizando a funcionalidade de regra de resposta automatica.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contextmessage_service = ContextMessageService.new(API_KEY)
result = @contextmessage_service.get_report(
  "yyyy-MM-dd HH:mm", # StartDate: Data inicial a ser filtrado o relatorio.
  "yyyy-MM-dd HH:mm", # EndDate: Data final a ser filtrado o relatorio.
  "ContextRuleName")  # ContextRuleName: Pode ser passado em branco caso nao queira filtrar a regra especifica que enviada.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object":  [
    {
      "Sender": "", 
      "Content": "", 
      "Received": "", 
      "ContextRuleName": "", 
      "StatusMessage": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Consultar Relatório / Respostas

Com este recurso, é possivel consultar todos os detalhes disponíveis dos SMS recebidos utilizando a funcionalidade de recebimento de respostas.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@reply_service = ReplyServiceMessage.new(API_KEY)
result = @reply_service.get_report(
  "yyyy-MM-dd HH:mm", # StartDate: Data inicial a ser filtrado o relatorio.
  "yyyy-MM-dd HH:mm", # EndDate: Data final a ser filtrado o relatorio.
  "Sender")           # Sender: Pode ser passado em branco caso nao queira filtrar uma resposta. E o numero do telefone de quem ou o que respondeu o SMS.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Sender": "",
      "SentContent": "",
      "ReceivedContent": "",
      "ReceivedDate": "",
      "SenderName": ""
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Receber Respostas / Callback

Com este recurso, é possivel receber ao invés de consultar todos os detalhes disponíveis dos SMS recebidos utilizando a funcionalidade de recebimento de respostas.

Configuração da URL

Antes de mais nada, para receber as respostas via callback, é necessário que você ja tenha construído em sua aplicação um webhook para receber a resposta no padrão a seguir, além disso é necessário que o endpoint do seu webhook seja público e que você tenha configurado em sua conta seguindo os seguintes passos:
1 - Acessar o painel em https://sms.comtele.com.br, e inserir os dados de acesso de sua conta.
2 - Na opção Configurações do menu lateral, clique em Alterar Meus Dados.
3 - Na tela de edição dos seus dados pessoais, localize a seção CONFIGURAÇÕES e a opção URL de Callback de Respostas, insira a URL do webhook que irá receber as respostas e clique no botão salvar.
Feito esses passos, em um intervalo máximo de 30 minutos, todas as respostas que estiverem atrelados aos SMS enviados pelo seu usuário serão retornados via callback.

Exemplo do objeto da resposta

  {
    "Sender":string,
    "SentContent":string,
    "ReceivedContent":string,
    "ReceiveDate":"yyyy-MM-ddThh:mm:ss.ms",
    "SenderName":string
  }

Campos do Retorno

Cadastrar / Grupos de Contatos

Com este recurso, é possivel cadastrar grupos de contatos para segmentar estes contatos em listas que podem ser usadas no momento do envio.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contact_service = ContactService.new(API_KEY)
result = @contact_service.create_group(
  "GroupName",    # GroupName: Nome do grupo a ser cadastrado.
  "Description")  # Description: Breve descricao do grupo a ser cadastrado.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Name": "group_name",
    "Description": "group_description"
  },
  "Message": "O grupo de contatos foi criado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar / Grupos de Contatos

Com este recurso, é possivel consultar os grupos de contatos cadastrados.

Consultar Todos os Grupos

Com este recurso, é possivel consultar detalhes de todos os grupos de contatos cadastrados em sua conta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contact_service = ContactService.new(API_KEY)
result = @contact_service.get_all_groups()

puts result

Consultar Grupo Específico

Com este recurso, é possivel consultar detalhes filtrando um grupo de contatos específico cadastrado em sua conta.

from comtele_sdk.contact_service import ContactService

api_key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

contact_service = ContactService(API_KEY)
result = contact_service.get_group_name(
  'GroupName')  # GroupName: Nome do grupo a ser filtrado os detalhes.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Id": comtele_group_id,
      "Name": "group_name",
      "Description": "group_description",
      "TotalContacts": 1,
      "LastUsed": "yyyy-MM-dd HH:mm:ss.ms"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Excluir / Grupos de Contatos

Com este recurso, é possivel excluir grupos de contatos cadastrados.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contact_service = ContactService(API_KEY)
result = @contact_service.remove_group(
  "GroupName") # GroupName: Nome do grupo a ser excluido.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": null,
  "Message": "O grupo de contatos foi removido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Cadastrar Contatos / Grupos de Contatos

Com este recurso, é possivel cadastrar contatos em grupos para segmentar estes contatos em listas que podem ser usadas no momento do envio.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contact_service = ContactService(API_KEY)
result = @contact_service.add_contact_to_group(
  "GroupName",    # GroupName: Nome do grupo ja existente.
  "11999998888",  # ContactPhone: Numero de telefone do contato a ser cadastrado. 
  "ContactName")  # ContactName: Nome do contato a ser cadastrado, pode ser informado em branco.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "GroupName": "group_name",
    "Action": "add_number",
    "ContactPhone": "phone_number",
    "ContactName": "contact_name"
  },
  "Message": "O contato foi inserido no grupo com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Excluir Contatos / Grupos de Contatos

Com este recurso, é possivel remover contatos em grupos segmentados, para que estes contatos não recebam mais SMS destas listas quando usadas no momento do envio.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@contact_service = ContactService(API_KEY)
result = @contact_service.remove_contact_from_group(
  "GroupName",    # GroupName: Nome do grupo que o contato esta cadastrado.
  "11999998888")  # ContactPhone: Numero de telefone do contato a ser excluido.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "GroupName": "group_name",
    "Action": "remove_number",
    "ContactPhone": "phone_number",
    "ContactName": "contact_name"
  },
  "Message": "O contato foi removido do grupo com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Cadastrar Contatos / Lista de Bloqueios

Com este recurso, é possivel adicionar números de telefone em uma Lista de Bloqueios para não receber mais SMS proveniente de sua conta, assim, você pode se despreocupar com uma verificação antes de mandar uma mensagem para números que não desejam mais receber seus SMS, basta adicionar estes telefones em sua blacklist, e caso seja enviado um SMS para este número, não será consumido crédito, o SMS não será entregue e aparecerá no relatório detalhado, uma mensagem informando que o número não recebeu o SMS pois está cadastrado na blacklist.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@blacklist_service = BlacklistService.new(API_KEY)
result = @blacklist_service.insert(
  "11999998888")  # PhoneNumber: Numero de telefone do contato a ser adicionado na Lista de Bloqueios.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "PhoneNumber": "",
    "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
  },
  "Message": "O numero foi inserido na Lista de Bloqueios com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Contatos / Lista de Bloqueios

Com este recurso, é possivel consultar os números de telefone e a data que foram adicionados na sua Lista de Bloqueios.

Consultar Todos Telefones

Com este recurso, é possivel consultar detalhes de todos os contatos cadastrados em sua Lista de Bloqueios.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@blacklist_service = BlacklistService.new(API_KEY)
result = @blacklist_service.get_blacklist()

puts result

Consultar Telefone Específico

Com este recurso, é possivel consultar detalhes filtrando um contato específico cadastrado em sua Lista de Bloqueios.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@blacklist_service = BlacklistService.new(API_KEY)
result = @blacklist_service.get_by_phone_number(
  "11999998888")  # PhoneNumber: Numero de telefone do contato a ser consultado na Lista de Bloqueios.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "PhoneNumber": "phone_number",
      "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Excluir Contatos / Lista de Bloqueios

Com este recurso, é possivel remover números de telefone que foram adicionados na Lista de Bloqueios para voltar a receber os SMS provenientes de sua conta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@blacklist_service = BlacklistService.new(API_KEY)
result = @blacklist_service.remove(
  "11999998888")  # PhoneNumber: Numero de telefone do contato a ser excluido na Lista de Bloqueios.

puts result

Exemplo de Retorno de Sucesso

  {
    "Success": true,
    "Object": {
      "PhoneNumber": "",
      "BlacklistDate": "yyyy-MM-ddTHH:mm:ss.ms"
    },
    "Message": "O numero foi removido da Lista de Bloqueios com sucesso."
  }

Campos do Retorno

Retornos Previsíveis

Consultar Saldo

Com este recurso, é possivel consultar a quantidade de saldo disponível em sua conta ou subcontas.

Consultar Saldo

Com este recurso, é possivel consultar saldo de sua conta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@credit_service = CreditService.new(API_KEY)
result = @credit_service.get_my_credits()

puts result

Consultar Saldo Subcontas

Com este recurso, é possivel consultar saldo de suas subconta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@credit_service = CreditService.new(API_KEY)
result = @credit_service.get_credits(
  "Username") # Username: Username da subconta a ter o saldo consultado.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": 0,
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Inserir Saldo / Subcontas

Com este recurso, é possivel adicionar saldo em suas subcontas. Recurso disponível apenas para contas do tipo revenda

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@credit_service = CreditService.new(API_KEY)
result = @credit_service.add_credits(
  "Username") # Username: Username da subconta a ter o credito inserido ou removido.
  "Amount")   # Amount: Quantidade de creditos a ser adicionada, o valor tambem pode ser negativo para remover o credito.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": null,
  "Message": "Os creditos foram alterados com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Consultar Histórico de Recargas / Subcontas

Com este recurso, é possivel consultar a histórico de créditos adicionados suas subcontas. Recurso disponível apenas para contas do tipo revenda

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@credit_service = CreditService.new(API_KEY)
result = @credit_service.get_history(
  "Username") # Username: Username da subconta a ter o historico de recargas consultado.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": [
    {
      "Amount": 1,
      "Balance": 1,
      "ExpiryDate": null,
      "HistoryDate": "yyyy-MM-dd HH:mm.ms",
      "AssociadedUsername": "username"
    }
  ],
  "Message": null
}

Campos do Retorno

Retornos Previsíveis

Cadastrar / Subcontas

Com este recurso, é possivel cadastrar subcontas, se a sua conta for do tipo revenda. Dessa maneira é possível separar completamente a utilização das funcionalidades, créditos e acesso.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@account_service = AccountService.new(API_KEY)
result = @account_service.create_account(
  "Comtele",              # Firstname: Primeiro nome da pessoa, ou nome da empresa a ser cadastrada.
  "test@comtele.com.br",  # Email: Email de contato do responsavel pela conta.
  "14121127000173",       # CorporateTaxpayer: CNPJ da empresa se for pessoa juridica.
  "00000000000",          # IndividualTaxpayer: CPF do responsavel se for pessoa fisica.
  "11999998888",          # MobileNumber: Numero de telefone do responsavel pela conta.
  "pass4w")               # Password: Senha da conta a ser cadastrada.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Enabled": true,
    "Username": "sub_account_username",
    "Balance": 0,
    "Connection": null,
    "LastBalanceHistory": null
  },
  "Message": "O usuario foi inserido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Consultar / Subcontas

Com este recurso, é possivel consultar as subcontas cadastradas e atreladas a sua conta.

Consultar Todos as Subcontas

Com este recurso, é possivel consultar detalhes de todas as subcontas cadastrados em sua conta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@account_service = AccountService.new(API_KEY)
result = @account_service.get_all_accounts()

puts result

Consultar Subconta Específica

Com este recurso, é possivel consultar detalhe de uma subconta específica atrelada a sua conta.

require 'comtele_sdk'
include ComteleSdk

API_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

@account_service = AccountService.new(API_KEY)
result = @account_service.get_account_by_username(
  "Username") # Username: Username da subconta que deve ser consultado os detalhes cadastrais.

puts result

Exemplo de Retorno de Sucesso

{
  "Success": true,
  "Object": {
    "Enabled": true,
    "Username": "sub_account_username",
    "Balance": 0,
    "Connection": yyyy-MM-ddTHH:mm:ss.ms,
    "LastBalanceHistory": yyyy-MM-ddTHH:mm:ss.ms
  },
  "Message": "O usuario foi inserido com sucesso"
}

Campos do Retorno

Retornos Previsíveis

Node.js

Instalação da SDK

comtele-sdk está disponível no NPM o código é open source e pode ser encontrado em nosso GitHub github.com/comtele.

A versão mínima necessária do Node para instalar a SDK é a 6.9.0, caso esteja utilizando uma versão inferior recomendamos que utilize o NVM, além disso, você pode dar uma olhadinha no nosso GitHub como fazer as chamadas via API Rest e fazer a sua própria versão.

$ npm install comtele-sdk

Enviar SMS

Com este recurso, é possivel enviar SMS de forma instantânea.

const TextMessageService = require('comtele-sdk').TextMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var textMessageService = new TextMessageService(apiKey);
textMessageService.send(
  "my_id",          // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Nodejs",   // Content: Conteudo da mensagem a ser enviada.
  ["11999998888"],  // Receivers: Numero de telefone que vai ser enviado o SMS.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Regra de Resposta Automática

Com este recurso, é possivel enviar SMS de forma instantânea e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

const ContextMessageService = require('comtele-sdk').ContextMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var contextMessageService = new ContextMessageService(apiKey);
contextMessageService.send(
  "my_id",            // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "ContextRuleName",  // ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  ["11999998888"],    // Receivers: Numero de telefone que vai ser enviado o SMS.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Enviar SMS / Grupos de Contatos

Com este recurso, é possivel enviar SMS de forma instantânea para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

const ContactMessageService = require('comtele-sdk').ContactMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var contactMessageService = new ContactMessageService(apiKey);
contactMessageService.send(
  "my_id",            // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Nodejs",     // Content: Conteudo da mensagem a ser enviada.
  "GroupName",        // GroupName: Nome do grupo de contatos que receberao o SMS
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados.

const TextMessageService = require('comtele-sdk').TextMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var textMessageService = new TextMessageService(apiKey);
textMessageService.schedule(
  "my_id",            // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Nodejs",     // Content: Conteudo da mensagem a ser enviada.
  "yyyy-MM-dd HH:mm", // ScheduleDate: Data que o SMS deve ser disparado.
  ["11999998888"],    // Receivers: Numero de telefone que vai ser enviado o SMS.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Campos do Retorno

Retornos Previsíveis

Agendar SMS / Regra de Resposta Automática

Com este recurso, é possivel programar a data e horário de envio de SMS para serem enviados, e quando o SMS for respondido, é possivel enviar uma resposta de forma automática, baseado em um contexto previamente configurado.
Para utilizar este recurso, é necessário que você acesse a opção Resposta Automática no menu Configurações no painel de SMS, cadastre uma regra de resposta automática e informe o nome que foi cadastrado no campo ContextRuleName no momento que for usar o endpoint.

const TextMessageService = require('comtele-sdk').TextMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var textMessageService = new TextMessageService(apiKey);
textMessageService.schedule(
  "my_id",            // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "ContextRuleName",  // ContextRuleName: Nome da regra de resposta automatica a ser usada no envio.
  "yyyy-MM-dd HH:mm", // ScheduleDate: Data que o SMS deve ser disparado.
  ["11999998888"],    // Receivers: Numero de telefone que vai ser enviado o SMS.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Agendar SMS / Grupos de Contatos

Com este recurso, é possivel programar a data e horário de envio de SMS para um grupo de contatos.
Para usar este recuso, é necessário ter grupos de contatos já cadastrados em nossa aplicação, caso ainda não tenha feito isso, dê uma olhadinha no recurso Cadastrar Grupos e Adicionar Contatos / Grupos

const TextMessageService = require('comtele-sdk').TextMessageService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var textMessageService = new TextMessageService(apiKey);
textMessageService.schedule(
  "my_id",            // Sender: Id de requisicao da sua aplicacao para ser retornado no relatorio, pode ser passado em branco.
  "Hello Nodejs",     // Conteudo da mensagem a ser enviada.
  "GroupName",        // GroupName: Nome do grupo de contatos que receberao o SMS.
  "yyyy-MM-dd HH:mm", // ScheduleDate: Data que o SMS deve ser disparado.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": null, 
  "Message": "A requisicao de envio foi encaminhada para processamento com sucesso. Voce podera acompanhar o status pelos relatorios."
}

Retornos Previsíveis

Enviar SMS / Dois Fatores

Com este recurso, é possivel enviar via SMS de forma instantânea um código de autenticação para o destinatário, que pode ser validado posteriormente no endpoint a seguir: Validar Código / Dois Fatores.

const TokenService = require('comtele-sdk').TokenService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var tokenService = new TokenService(apiKey);
tokenService.sendToken(
  "11999998888",  // PhoneNumber: Numero de telefone que vai ser enviado o token via SMS.
  "Company",      // Prefix: Identificação da empresa que aparecerá no corpo da mensagem.
  (result) => console.log(result));

Exemplo de Retorno de Sucesso

{
  "Success": true, 
  "Object": {
    "Prefix": "", 
    "PhoneNumber": ""
    }, 
  "Message": 
  "O token foi criado com sucesso."
}

Campos do Retorno

Retornos Previsíveis

Validar Código / Dois Fatores

Com este recurso, é possivel validar o token recebido e informado pelo usuário que recebeu o SMS, enviado pelo endpoint anterior anterior: Enviar SMS / Dois Fatores.

const TokenService = require('comtele-sdk').TokenService;
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

var tokenService = new TokenService(apiKey);
tokenService.validateToken(
  "TokenCode",  // TokenCode: Token que o cliente informou e deve ser validado pela Comtele.
  (result) => console.log(result));