Teleguiado API Última atualização: 28-06-2020

Bem vindo a API do Teleguiado. Com ela você pode enviar mensagens SMS/WhatsApp e receber status de entrega e respostas dos usuários de forma automática.

Nossa API suporta nativamente o formato: REST

O sistema deve realizar uma chamada enviando os parâmetros por meio de GET ou POST.

O retorno para cada chamada será um JSON cujo formato é detalhado ao longo desta documentação.

Padrão da URL dos Web Services:

Todos as requisições são disponibilizadas via REST pela seguinte url:

{protocolo}://{servidor}:{porta}/{módulo}/rest/api/{serviço}

Dados da url:

protocolo: http ou https
servidor: {HOST}
porta: 8080 (8443 para https)
módulo: sms-main-module/rest/api
Exemplo: https://{HOST}:8443/sms-main-module/rest/api/{serviço}

1.1 Autenticação

Todas as requisições da API do Teleguiado devem utilizar cabeçalhos incluíndo o Token de acesso.

Existem dois tipos de Tokens o baseado no usuário e senha e o Token de login.

Caso haja erro na autenticação, o respectivo código de erro será retornado.

Tokens baseados no usuário e senha:

É formado pela chave Base64 da sua conta e senha. Exemplo para obter o valor, utilizando o comando base64 do linux:

O formato é: usuário:senha

$ echo -n usuário:senha | base64
Y29udGE6c2VuaGE=

O site base64Encode também faz essa codificação gratuitamente.

Token de Acesso Baseado no login:

É recebido no momento em que o login é efetuado através do serviço de login que será descrito no respectivo item.

O Token é codificado no formato Base64 e criptografado.

Quando a utilização dos serviços for finalizada, ao usar a requisição com o Token baseado no login, pode-se efetuar o logout da aplicação utilizando o serviço de logout. Caso não seja feito o logout, o timeout é de 30 minutos. Caso nenhuma requisição seja feita neste período, o usuário é automaticamente desconectado. E as requisições receberão o código de retorno 419 (Authentication Timeout).

1.2 Envio Simples HTTP (GET)

Esse tipo de envio é controlado pela fila de execução!

Método de Solicitação: GET

Serviço: /messages/simple

Cabeçalho:

Content-Type: application/x-www-form-urlencoded
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

phone: número de telefone a ser enviada a mensagem
sendmethod: método de envio (SMS ou WHATSAPP)
message: mensagem a ser enviada

Exemplo:

/messages/simple?phone={mobilephone}&sendmethod={sms}&message={message}

JSON da resposta:

	{
		"statusCode": 0,
		"statusDescription": "Message sent",
		"messageId": 321654,
		"phone": "5551999998888"
	}

JSON da resposta em caso de erro:

	{
		"statusCode": -1,
		"statusDescription": "Bad request - parameter error",
		"messageId": null,
		"phone": null
	}

Imagem de exemplo:

1.3 Envio Múltiplo HTTP (POST)

Esse tipo de envio é controlado pela fila de execução!

Método de Solicitação: POST

Serviço: /messages/multi

Cabeçalho:

Content-Type: application/json
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

sendMethod: método de envio (SMS ou WHATSAPP)
messages: lista de mensagens contendo o número e o texto da mensagem (Limitado em 500 por requisição)

phone: número de telefone a ser enviada a mensagem
message: mensagem a ser enviada

downtime (opcional): mensagem de renitência

minutes: tempo em minutos de espera para enviar a mensagem de renitência
message: mensagem de renitência a ser enviada

Exemplo:

JSON da requisição:

	{
		"sendMethod": "SMS",
		"messages": [{
			"phone": "51999999999",
			"message": "Texto da mensagem 1!"
		},{
			"phone": 51999999998,
			"message": "Texto da mensagem 2!"
		}],
		"downtime":{
			"minutes": 5,
			"message": "Texto da mensagem de renitência!"
		}
	}

JSON da resposta:

	{
		"“size": 2,
		"messageList": [{
			"id": 444444,
			"phone": "51999999999",
			"status": 0
			},{
			"id": 444445,
			"phone": "51999999998",
			"status": 0
		}]
	}

JSON da resposta em caso de erro:

	{
		"statusCode": -1,
		"statusDescription": "Bad request - parameter error",
		"messageId": null,
		"phone": null
	}

Imagem de exemplo:

1.4 Códigos de Status

Message sent: 0
Bad request - parameter error: -1
Parameter not found - user: -2
Parameter not found - password: -3
Parameter not found - phone: -4
Parameter not found - message: -5
Unknown user: -6
Blacklist number: -7
Message to long: -8
Invalid number: -9
Invalid IP: -10
Unsupported encoding exception: -11
Permission denied: -12
Amount of message exceeded: -14
Unknown error: 99

1.5 Envio de Mensagem Avulsa

Esse tipo de mensagem tem prioridade na fila de execução.

Aviso

A mensagem é igual para todos os números na mesma requisição.

Limite de 10 mensagens por requisição.

Método de Solicitação: POST

Serviço: /messages/single

Cabeçalho:

Content-Type: application/json
Token: ExemploLyfbeDLk1VAo1LvBoTc/iOOVEzcBCes= Token de usuário e senha (Base64 => user:password)

Parâmetros:

sendMethod: método de envio (SMS ou WHATSAPP)
phones: lista contendo os números de telefone para qual a mensagem será enviada (máximo 10).
text: mensagem a ser enviada
downtime (opcional): mensagem de renitência

minutes: tempo em minutos de espera para enviar a mensagem de renitência
message: mensagem de renitência a ser enviada

Exemplo:

JSON da requisição:

	{
		"sendMethod": "SMS",
		"phones": ["5551988887777", "51988887777"],
		"text": "Mensagem de texto",
		"downtime":{
			"minutes": 5,
			"message": "Texto da mensagem de renitência!"
		}		
	}

JSON da resposta (lista contendo os identificadores de cada mensagem):

	{
		"[ 5100200 ]"
	}

Imagem de exemplo:

1.6 Envio de Campanha Direta

Esse tipo de envio é controlado pela fila de execução!

Método de Solicitação: POST

Serviço: /campaign

Cabeçalho:

Content-Type: application/json
Token: ExemploLyfbeDLk1VAo1LvBoTc/iOOVEzcBCes= Token de usuário e senha (Base64 => user:password)

Parâmetros:

sendMethod: método de envio (SMS ou WHATSAPP).
name: nome da campanha a ser cadastrada.
messageInfo: lista de mensagens a serem enviadas.

phoneNumber: número do telefone.
text: mensagem a ser enviada.

downtime (opcional): mensagem de renitência

minutes: tempo em minutos de espera para enviar a mensagem de renitência
message: mensagem de renitência a ser enviada

JSON da requisição:

	{
		"sendMethod": "SMS",
		"name": "Contatos 1",
		"messageInfo": [{ 
			"phone": "51999999999",
			"text": "Texto Livre"
		}],
		"downtime":{
			"minutes": 5,
			"message": "Texto da mensagem de renitência!"
		}		
	}

JSON da resposta:

	{
		"size": 2,
		"messageList": [{
			"id": 444444,
			"phone": "51999999999",
			"status": 0
		}]
	}

Imagem de exemplo:

1.7 Envio de mensagem direta via WhatsApp

Esse tipo de envio não é controlado pela fila de execução!

Sem fila de execução entra na prioridade de envio.

Canal de comunicação WhatsApp

Para efetuar esse tipo de envio é necessário ter um canal de comunicação WhatsApp cadastrado e uma conta do Teleguiado WhatsappBot ativa.

Para enviar imagem, arquivo, áudio ou vídeo basta enviar uma URL do item como texto da mensagem. Não é possível enviar texto e arquivo ao mesmo tempo.

O tempo de intervalo de envio das mensagens deve ser controlada pelo cliente que está integrando.

A URL de envio segue o padrão informado a seguir:

Dados da URL::

protocolo: http ou https
servidor: HOST
porta: 8080 (8443 para https)
módulo: /whatsapp/unique

Método de Solicitação: POST

Exemplo: https://{HOST}:8443/whatsapp/unique

Cabeçalho:

Content-Type: application/json
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

sender: {id: número do whatsapp}.
recipient: {id: identificador do canal}.
message: {text: texto da mensagem}.

JSON da requisição:

	{
		"sender": {"id": "51999999999"},
		"recipient": {"id": "76DF5becfa3"},
		"message": {"text": "Mensagem via Whatsapp"}
	}

JSON da resposta:

	{
		"messageId": 2
	}

1.8 Atendimento Offline

1.8.1 Cadastro de Atividade

Cadastro de atividades para o Atendimento Offline.

Caso não for informado o tempo de execução da atividade será atribuído o valor de uma hora (1).

Método de Solicitação: POST

Serviço: /activity

Cabeçalho:

Content-Type: application/json
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

department: Departamento que a atividade será vinculada.
name: Nome atribuído para a atividade.
description: Descrição da atividade.
timeToFinish: Tempo de execução da atividade em horas.

JSON da requisição:

	{
		"department": {"id": 999},
		"name": "Cadastro de Atividade",
		"description": "Contactar cliente em 22/12/2020",
		"timeToFinish": 3
	}

JSON da resposta:

	{
		"id": 3333,
		"account": {"@type": "Company", "id": 222},
		"unit": {"id": 111},
		"department": {"id": 999},
		"name": "Cadastro de Atividade",
		"description": "Contactar cliente em 22/12/2020",
		"status": "PENDING",
		"timeToFinish": 3,
		"createdAt": 1593112904720
	}

Possíveis erros de retorno:

UNKNOWN_ACTIVE_NAME: Envio da atividade sem nome.
UNKNOWN_DEPARTMENT: Departamento desconhecido.
UNKNOWN_TOKEN: Token não identificado.
UNKNOWN_USER: Usário desconhecido.
DEPARTMENT_NOT_FOUND: Departamento não encontrado.

Imagem de exemplo:

Imagem de exemplo de uso no teleguiado:

1.8.2 Consultar Atividade

Consulta de atividade do Atendimento Offline.

A busca é feita pelo ID da atividade informado no momento do cadastro da atividade.

A consulta somente retornará a atividade vinculada à conta em que o usuário está cadastrado.

Método de Solicitação: GET

Serviço: /activity

Cabeçalho:

Content-Type: application/x-www-form-urlencoded
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

activityId: Identificador da atividade.
departmentId: Identificador do departamento.

Exemplo:

/activity?activityId={activityID}&departmentId={departmentID}

JSON da resposta:

	{
		"id": 3333,
		"account": {"@type": "Company", "id": 222},
		"unit": {"id": 111},
		"department": {"id": 999},
		"name": "Cadastro de Atividade",
		"description": "Contactar cliente em 22/12/2020",
		"status": "PENDING",
		"timeToFinish": 3,
		"finishTime": 1593112904720,
		"updatedAt": 1593112904720,
		"createdAt": 1593112904720
	}

Possíveis erros de retorno:

PARAMETERS_ERROR: Erro de parâmetros.
PARAMETER_ID_NOT_FOUND: Parâmetro ID não encontrado.
UNKNOWN_TOKEN: Token não identificado.
UNKNOWN_USER: Usário desconhecido.
DEPARTMENT_NOT_FOUND: Departamento não encontrado.
UNKNOWN_ERROR: Erro desconhecido.

Imagem de exemplo:

2.1 Blacklist

2.1.1 Cadastro de Número

Cadastro de número na Blacklist.

Método de Solicitação: POST

Serviço: /blacklist

Cabeçalho:

Content-Type: application/json
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

number: Número
reason: Motivo para ter cadastrado o número.

JSON da requisição:

	{
		"number": "9999999999",
		"reason": "Número não registrado na rede."
	}

JSON da resposta:

	{
		"phoneNumber": {
			"countryCode": "55",
			"regionCode": "51",
			"number": "988887777",
			"fullNumber": "5551988887777"
		},
		"number": 5551988887777,
		"reason": "Número não registrado na rede."
	}

Possíveis erros de retorno:

UNKNOWN_PHONE_NUMBER: Parâmetro número não encontrado.
UNKNOWN_TOKEN: Token não identificado.
UNKNOWN_USER: Usário desconhecido.
PERMISSION_DENIED: Sem permissão para cadastro.
UNKNOWN_ERROR: Departamento desconhecido.

Imagem de exemplo:

2.1.2 Consultar Número

Consulta de número na blacklist.

Método de Solicitação: GET

Serviço: /blacklist

Cabeçalho:

Content-Type: application/x-www-form-urlencoded
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

phone: Número do telefone.

Exemplo:

/blacklist?phone={NUMERO}

JSON da resposta:

	{
		"phoneNumber": {
			"countryCode": "55",
			"regionCode": "51",
			"number": "988887777",
			"fullNumber": "5551988887777"
		},
		"number": 5551988887777,
		"createDate": 1616008874383,
		"reason": "Número não registrado na rede."
	}

Possíveis erros de retorno:

UNKNOWN_PHONE_NUMBER: Parâmetro número não encontrado.
UNKNOWN_TOKEN: Token não identificado.
UNKNOWN_USER: Usário desconhecido.
PERMISSION_DENIED: Sem permissão para cadastro.
UNKNOWN_ERROR: Departamento desconhecido.

Imagem de exemplo:

3.1 Envio de Template

3.1.1 Múltiplo HTTP (POST)

Esse tipo de envio é controlado pela fila de execução!

Método de Solicitação: POST

Serviço: /messages/multi

Cabeçalho:

Content-Type: application/json
Token: ExemploM2MC5uZXQuYnI6dGVzdA== Token de usuário e senha (Base64 => user:password)

Parâmetros:

sendMethod: método de envio (PROVIDER)
messages: lista de mensagens contendo o número e o texto da mensagem (Limitado em 500 por requisição)

phone: número de telefone a ser enviada a mensagem
templateMessageName: Nome do template a ser enviado
templateVariables (opcional): Variáveis do template (Limite de 2 variáveis)

Exemplo:

JSON da requisição:

	{
		"sendMethod": "PROVIDER",
		"messages": [{
			"phone": "51999999999",
			"templateMessageName": "1633646884341_teste",
			"templateVariables": "João;Aprovado"
		},{
			"phone": 51999999998,
			"templateMessageName": "1633646884341_teste",
			"templateVariables": "Pedro;Reprovado"
		}]
	}

JSON da resposta:

	{
		"“size": 2,
		"messageList": [{
			"id": 444444,
			"phone": "51999999999",
			"status": 0
			},{
			"id": 444445,
			"phone": "51999999998",
			"status": 0
		}]
	}

JSON da resposta em caso de erro:

	{
		"statusCode": -1,
		"statusDescription": "Bad request - parameter error",
		"messageId": null,
		"phone": null
	}

Imagem de exemplo:

3.1.2 Mensagem Avulsa

Esse tipo de mensagem tem prioridade na fila de execução.

Aviso

A mensagem é igual para todos os números na mesma requisição.

Limite de 10 mensagens por requisição.

Método de Solicitação: POST

Serviço: /messages/single

Cabeçalho:

Content-Type: application/json
Token: ExemploLyfbeDLk1VAo1LvBoTc/iOOVEzcBCes= Token de usuário e senha (Base64 => user:password)

Parâmetros:

sendMethod: método de envio (PROVIDER)
phones: lista contendo os números de telefone para qual a mensagem será enviada (máximo 10).
templateMessageName: Nome do template a ser enviado
templateVariables (opcional): Variáveis do template (Limite de 2 variáveis)

Exemplo:

JSON da requisição:

	{
		"sendMethod": "PROVIDER",
		"phones": ["5551988887777", "51988887777"],
		"templateMessageName": "ticket_check",		
		"templateVariables": "Matrículas;11/12/2024"		
	}

JSON da resposta (lista contendo os identificadores de cada mensagem):

	{
		"[ 5100200, 5100201 ]"
	}