Desenvolvimento

Métodos da API

A seguir, você encontra uma referência completa dos métodos disponíveis na API. Esses métodos permitem que você faça a integração de seu sistema por meio de chamadas HTTP ou WebService.



Descrição


Enviar uma mensagem SMS para um único celular de destino.



Método de Enviar por Json

Verbo HTTP: Post

Endpoint: https://api-sms.talkcomm.com.br/api/EnvioSimples/EnviarJson

Parâmetros de entrada


Observação: Para este método, caso o campo não seja obrigatório, não é necessário adicionar ao formulário a menos que se queira passar um valor.

Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
ContaId Não Body Inteiro Identificador da conta utilizada pelo cliente (encontrado em https://sms.talkcomm.com.br/ClienteConta/List).
CampanhaId Não Body Inteiro Identificador da campanha utilizada pelo cliente (encontrado em https://sms.talkcomm.com.br/Campanha/List).
NA Não Body String (20) Número de telefone a ser binado no destino (exige contratação prévia). Opcional: deve-se enviar em branco caso não utilize.
NB Sim Body código de país + código de área + número (até 15 dígitos) Celular de destino. Exemplo: 5511999887766.
Mensagem Sim Body String Texto do SMS. Deve conter no máximo 147 caracteres (140 para destinatários Nextel).
DataInicio Sim Body aaaa-MM-dd hh:mm:ss Data para o disparo. É possível agendar data e hora para o envio, no formato: aaaa-MM-dd hh:mm:ss, caso enviado data anterior a data atual será disparado imediatamente a mensagem.
CodigoIntegracao Sim Body String (50) Identificador único para o SMS.
TipoEnvioId Não Body 1 – envia tradicional (padrão)
2 – envia flash 		Tipo de envio do SMS. Se o parâmetro TipoEnvioId não for fornecido será enviado como tradicional. Importante: Para envio tipo flash é necessário contratação prévia.

Exemplo JSON


			{
				"ApiKey": "[ApiKey]",
				"ContaId":"[CONTA_ID]",
				"CampanhaId":"[CAMPANHA_ID]",
				"NA":"[NUMERO_ORIGEM]",
				"NB":"[NUMERO_DESTINO]",
				"Mensagem":"[MENSAGEM]",
				"DataInicio":"[DATA_AGENDAMENTO]",
				"CodigoIntegracao":"[ID_MENSAGEM]",
				"TipoEnvioId":"[TIPO_ENVIO_ID]"
			}



Descrição


Enviar, em uma mesma chamada, até 10 mil SMS para múltiplos destinatários.
A lista de destinatários pode ser enviada como uma variável HTTP POST. Veja a seguir.


Método de Enviar por Json

Verbo HTTP: Post

Endpoint: https://api-sms.talkcomm.com.br/api/EnvioMultiplo/EnviarJson

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
ContaId Não Body Inteiro Identificador da conta utilizada pelo cliente (encontrado em https://sms.talkcomm.com.br/ClienteConta/List).
CampanhaId Não Body Inteiro Identificador da campanha utilizada pelo cliente (encontrado em https://sms.talkcomm.com.br/Campanha/List).
NA Não Body String (20) Número de telefone a ser binado no destino (exige contratação prévia). Opcional: deve-se enviar em branco caso não utilize.
NB Sim Body código de país + código de área + número (até 15 dígitos) Celular de destino. Exemplo: 5511999887766.
Mensagem Sim Body String Texto do SMS. Deve conter no máximo 147 caracteres (140 para destinatários Nextel).
DataInicio Sim Body aaaa-MM-dd hh:mm:ss Data para o disparo. É possível agendar data e hora para o envio, no formato: aaaa-MM-dd hh:mm:ss, caso enviado data anterior a data atual será disparado imediatamente a mensagem.
CodigoIntegracao Sim Body String (50) Identificador único para o SMS.
TipoEnvioId Não Body 1 – envia tradicional (padrão)
2 – envia flash 		Tipo de envio do SMS. Se o parâmetro TipoEnvioId não for fornecido será enviado como tradicional. Importante: Para envio tipo flash é necessário contratação prévia.

Exemplo JSON


			[
				{
					"ApiKey": "[ApiKey]",
					"ContaId": "[CONTA_ID]",
					"CampanhaId": "[CAMPANHA_ID]",
					"NA": "[NUMERO_ORIGEM]",
					"NB": "[NUMERO_DESTINO]",
					"Mensagem": "[MENSAGEM]",
					"DataInicio": "[DATA_AGENDAMENTO]",
					"CodigoIntegracao": "[ID_MENSAGEM]",
					"TipoEnvioId": "[TIPO_ENVIO_ID]"
				},
				{
					"ApiKey": "[ApiKey]",
					"ContaId": "[CONTA_ID]",
					"CampanhaId": "[CAMPANHA_ID]",
					"NA": "[NUMERO_ORIGEM]",
					"NB": "[NUMERO_DESTINO]",
					"Mensagem": "[MENSAGEM]",
					"DataInicio": "[DATA_AGENDAMENTO]",
					"CodigoIntegracao": "[ID_MENSAGEM]",
					"TipoEnvioId": "[TIPO_ENVIO_ID]"
				},
				{
					"ApiKey": "[ApiKey]",
					"ContaId": "[CONTA_ID]",
					"CampanhaId": "[CAMPANHA_ID]",
					"NA": "[NUMERO_ORIGEM]",
					"NB": "[NUMERO_DESTINO]",
					"Mensagem": "[MENSAGEM]",
					"DataInicio": "[DATA_AGENDAMENTO]",
					"CodigoIntegracao": "[ID_MENSAGEM]",
					"TipoEnvioId": "[TIPO_ENVIO_ID]"
				}
			]



Descrição


Consultar status de um SMS registrado na plataforma. Para realizar a consulta, é necessário que tenha sido utilizado o Identificador (Id) no momento do envio.
O retorno é uma linha de texto contendo o resultado da operação.


Método Consultar Delimitado

Verbo HTTP: Get

Endpoint: https://api-sms.talkcomm.com.br/api/ConsultaSimples/ConsultarDelimitado

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
CodigoIntegracao Sim Query String String (50) Identificador único para o SMS.

Exemplo de Consulta:


			https://api-sms.talkcomm.com.br/api/ConsultaSimples/ConsultarDelimitado?ApiKey=[ApiKey]&CodigoIntegracao=[ID_MENSAGEM]

Parâmetros de Saída


Posição Campo Descrição
0 CodigoIntegracao Identificador único do SMS.
1 NA Número de telefone a ser binado no destino.
2 NB Celular de destino.
3 Mensagem Texto do SMS.
4 DataCriacao Data que a mensagem foi cadastrada no sistema.
5 DataInicio Data para qual foi agendado o disparo da mensagem.
6 StatusId Id do Status da mensagem.
7 Descrição Descrição do Status da mensagem.
8 ContaId Id da conta usada para o envio da mensagem. Se não foi fornecido a conta no momento da criação da mensagem, este campo será preenchido com 0.
9 CampanhaId Id da campanha usada para o envio da mensagem. Se não foi fornecido a campanha no momento da criação da mensagem, este campo será preenchido com espaço em branco.

Exemplo de retorno da Consulta:

			TesteGet1;1178783366;11980687836;Teste Integracao Get;08/05/2013 11:25:51;08/05/2013 00:00:00;3;Entregue Celular;123;551000

Lista de StatusId de Mensagens


StatusId Status Descrição
1 Agendado
2 Entregue Operadora
3 Entregue Celular
5 Não Recebido
6 Higienizado
9 Erro ao Enviar
10 Saldo Insuficiente
11 BlackList
13 Não Encontrou Rota

Método Consultar Json

Verbo HTTP: Get

Endpoint: https://api-sms.talkcomm.com.br/api/ConsultaSimples/ConsultarJson

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
CodigoIntegracao Sim Query String String (50) Identificador único para o SMS.

Exemplo de Consulta:


			https://api-sms.talkcomm.com.br/api/ConsultaSimples/ConsultarJson?ApiKey=[ApiKey]&CodigoIntegracao=[ID_MENSAGEM]

Parâmetros de Saída


Campo Descrição
CampanhaId Id da campanha usada para o envio da mensagem. Se não foi fornecido a campanha no momento da criação da mensagem, este campo será preenchido com null.
ContaId Id da conta usada para o envio da mensagem. Se não foi fornecido a conta no momento da criação da mensagem, este campo será preenchido com 0.
NA Número de telefone a ser binado no destino.
NB Celular de destino.
Mensagem Texto do SMS.
DataInicio Data para qual foi agendado o disparo da mensagem.
DataCriacao Data que a mensagem foi cadastrada no sistema.
DataConfirmacao Data que a operadora de destino confirmou o envio para o celular.
CodigoIntegracao Identificador único do SMS.
StatusId Id do Status da mensagem.
StatusDescricao Descrição do Status da mensagem.

Exemplo de retorno da Consulta:

		{
			"CampanhaId": "CAMPANHA_ID",		
			"ContaId": "CONTA_ID",
			"NA": "1122225555",
			"NB": "11333338888",
			"Mensagem": "Sua Mensagem",
			"DataInicio": "2020-01-01T00:00:00",
			"DataCriacao": "2020-01-01T00:00:00",
			"DataConfirmacao": "2020-01-01T00:00:00",
			"CodigoIntegracao": "ID_MENSAGEM",
			"StatusId": "ID_STATUS",
			"StatusDescricao": "O Status Atual da Mensagem"
		}

Lista de StatusId de Mensagens


StatusId Status Descrição
1 Agendado
2 Entregue Operadora
3 Entregue Celular
5 Não Recebido
6 Higienizado
9 Erro ao Enviar
10 Saldo Insuficiente
11 BlackList
13 Não Encontrou Rota



Descrição


Consultar, em uma única chamada, status de várias mensagens registradas na plataforma.
Para realizar a consulta, é necessário que tenha sido utilizado o identificador (ID) no momento do envio.
O retorno é composto por linhas em formato texto correspondentes a cada ID enviado como parâmetro.
Importante: A consulta a um SMS fica disponível por até 24 horas após seu envio. Após esse período, será retornado “180 – message ID not found”.

Método Consultar JSON

Verbo HTTP: Post

Endpoint: https://api-sms.talkcomm.com.br/api/ConsultaMultiplo/ConsultarJson

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
ListaCodigoIntegracao Sim Body Array String(50) Lista de identificadores SMS

Exemplo de Consulta:


			{
				"ApiKey": "[ApiKey]",
				"ListaCodigoIntegracao": [
					"1",
					"2",
					"3"
				]
			}

Parâmetros de Saída


Campo Descrição
CampanhaId Id da campanha usada para o envio da mensagem. Se não foi fornecido a campanha no momento da criação da mensagem, este campo será preenchido com null.
ContaId Id da conta usada para o envio da mensagem. Se não foi fornecido a conta no momento da criação da mensagem, este campo será preenchido com 0.
NA Número de telefone a ser binado no destino.
NB Celular de destino.
Mensagem Texto do SMS.
DataInicio Data para qual foi agendado o disparo da mensagem.
DataCriacao Data que a mensagem foi cadastrada no sistema.
DataConfirmacao Data que a operadora de destino confirmou o envio para o celular.
CodigoIntegracao Identificador único do SMS.
StatusId Id do Status da mensagem.
StatusDescricao Descrição do Status da mensagem.

Exemplo de retorno da Consulta:

		[
			{
				"CampanhaId": "CAMPANHA_ID",		
				"ContaId": "CONTA_ID",
				"NA": "1122225555",
				"NB": "11333338888",
				"Mensagem": "Sua Mensagem",
				"DataInicio": "2020-01-01T00:00:00",
				"DataCriacao": "2020-01-01T00:00:00",
				"DataConfirmacao": "2020-01-01T00:00:00",
				"CodigoIntegracao": "ID_MENSAGEM",
				"StatusId": "ID_STATUS",
				"StatusDescricao": "O Status Atual da Mensagem"
			},
			{
				"CampanhaId": "CAMPANHA_ID",		
				"ContaId": "CONTA_ID",
				"NA": "1122225555",
				"NB": "11333338888",
				"Mensagem": "Sua Mensagem",
				"DataInicio": "2020-01-01T00:00:00",
				"DataCriacao": "2020-01-01T00:00:00",
				"DataConfirmacao": "2020-01-01T00:00:00",
				"CodigoIntegracao": "ID_MENSAGEM",
				"StatusId": "ID_STATUS",
				"StatusDescricao": "O Status Atual da Mensagem"
			}			
		]

Lista de StatusId de Mensagens


StatusId Status Descrição
1 Agendado
2 Entregue Operadora
3 Entregue Celular
5 Não Recebido
6 Higienizado
9 Erro ao Enviar
10 Saldo Insuficiente
11 BlackList
13 Não Encontrou Rota

Método Get

Verbo HTTP: Get

Endpoint: https://api-sms.talkcomm.com.br/api/ConsultaMultiplo/Get

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
ListaCodigoIntegracao Sim Query String String (8000) Lista de identificadores SMS separados por pipe '|'.
Exemplo: id0012|id0013|id0014

Exemplo de Consulta:


								https://api-sms.talkcomm.com.br/api/ConsultaMultiplo/Get?ApiKey=[ApiKey]&ListaCodigoIntegracao=[Lista_IDS_MENSAGEM]

Parâmetros de Saída


Campo Descrição
CampanhaId Id da campanha usada para o envio da mensagem. Se não foi fornecido a campanha no momento da criação da mensagem, este campo será preenchido com null.
ContaId Id da conta usada para o envio da mensagem. Se não foi fornecido a conta no momento da criação da mensagem, este campo será preenchido com 0.
NA Número de telefone a ser binado no destino.
NB Celular de destino.
Mensagem Texto do SMS.
DataInicio Data para qual foi agendado o disparo da mensagem.
DataCriacao Data que a mensagem foi cadastrada no sistema.
DataConfirmacao Data que a operadora de destino confirmou o envio para o celular.
CodigoIntegracao Identificador único do SMS.
StatusId Id do Status da mensagem.
StatusDescricao Descrição do Status da mensagem.

Exemplo de retorno da Consulta:

								[
									{
										"CampanhaId": "CAMPANHA_ID",		
										"ContaId": "CONTA_ID",
										"NA": "1122225555",
										"NB": "11333338888",
										"Mensagem": "Sua Mensagem",
										"DataInicio": "2020-01-01T00:00:00",
										"DataCriacao": "2020-01-01T00:00:00",
										"DataConfirmacao": "2020-01-01T00:00:00",
										"CodigoIntegracao": "ID_MENSAGEM",
										"StatusId": "ID_STATUS",
										"StatusDescricao": "O Status Atual da Mensagem"
									},
									{
										"CampanhaId": "CAMPANHA_ID",		
										"ContaId": "CONTA_ID",
										"NA": "1122225555",
										"NB": "11333338888",
										"Mensagem": "Sua Mensagem",
										"DataInicio": "2020-01-01T00:00:00",
										"DataCriacao": "2020-01-01T00:00:00",
										"DataConfirmacao": "2020-01-01T00:00:00",
										"CodigoIntegracao": "ID_MENSAGEM",
										"StatusId": "ID_STATUS",
										"StatusDescricao": "O Status Atual da Mensagem"
									}			
								]

Lista de StatusId de Mensagens


StatusId Status Descrição
1 Agendado
2 Entregue Operadora
3 Entregue Celular
5 Não Recebido
6 Higienizado
9 Erro ao Enviar
10 Saldo Insuficiente
11 BlackList
13 Não Encontrou Rota



Descrição


Excluir envios agendados que ainda não foram disparados através do código de integração.
Importante: A exclusão é irreversível!

Método Excluir por Código de Integração

Verbo HTTP: Delete

Endpoint: https://api-sms.talkcomm.com.br/api/Cancelamento/ExcluirPorCodigoIntegracao

Parâmetros de entrada


Parâmetro Obrigatório Local Parâmetro Formato Descrição
ApiKey Sim Query String String (36) ApiKey a associada a um usuário do TalkSMS (encontrado em https://sms.talkcomm.com.br/ClienteUsuario/List).
ListaCodigoIntegracao Sim Body Array String(50) Lista de identificadores SMS

Exemplo de Exclusão:


			{
				"ApiKey": "[ApiKey]",
				"ListaCodigoIntegracao": [
					"1",
					"2",
					"3"
				]
			}

Exemplo de retorno da Exclusão:

			"Excluídas 3 mensagens agendadas"

ATENÇÃO I: Se houver mais de uma mensagem agendada com o mesmo código de integração, todas as mensagens vinculadas a esse código de integração serão excluídas. Sendo assim a quantidade de mensagens excluídas pode ser maior que a quantidade de códigos de integração.


ATENÇÃO II: Se a mensagem que se solicitou a exclusão já foi enviada, então ela não será excluída. Sendo assim a quantidade de mensagens excluídas pode ser menor que a quantidade de códigos de integração.




Descrição


O webhook é acionado a partir do TalkSMS para um endpoint do lado do cliente, permitindo o recebimento das notificações em tempo real. É importante ressaltar que, para garantir o recebimento dos dados através do webhook, é necessário configurá-lo previamente dentro do portal do cliente. Esta configuração permite que o cliente especifique para onde os dados do webhook devem ser enviados, garantindo uma integração eficaz entre o TalkSMS e seus sistemas.

Método de Enviar por Json

Verbo HTTP: Post

Endpoint: https://SeuEndPoint.com.br

Parâmetros de saída


Parâmetro Obrigatório Formato Descrição
MensagemId Sim Int Codigo de Identificação da Mensagem na Plataforma TalkSMS
StatusId Sim Int Id dos Status da Mensagem no momento do disparo do Webhook
1 Agendado
2 Entregue Operadora
3 Entregue Celular
4 Entregue
5 Não Recebido
6 Higienizado
7 Aguardando Classificação
8 Aguardando Envio
9 Erro ao Enviar
10 Saldo Insuficiente
11 BlackList
12 Bloqueado - Não Tarifado
13 Não Encontrou Rota
StatusDescricao Sim String (36) Descricao dos Status
CodigoIntegracao Sim String (36) Codigo de Integracao da mensagem inicial, informado via API, Importacao Arquivo e etc
NA Sim String (36) Numero de Origem
NB Sim String (36) Numero de Destino
Mensagem Sim String (36) Mensagem
DataEnvio Sim yyyy/MM/ddTHH:mm:ss Data em que a Mensagem foi enviada ao Destinatario

Exemplo de visualização do Status:


			            {
				         MensagemId: 132 						               
	                    ,StatusId: {StatusId}					             
	                    ,StatusDescricao: {StatusDescricao}		               
	                    ,CodigoIntegracao: {CodigoIntegracao}	                
	                    ,NA: {NA}								                
	                    ,NB: {NB}								                
	                    ,Mensagem: {Mensagem}					                
	                    ,DataEnvio: {DataEnvio}	Ex: 2024-04-01T13:00:00
			            }

Tela de Gerenciamento:

URL: https://sms.talkcomm.com.br/ClienteWebhooks/List


Autenticação:

Descrição da imagem

Cadastro:

Descrição da imagem



Descrição


A resposta do webhook fornece uma maneira de comunicar de volta ao sistema remetente informações importantes sobre o status e o resultado da mensagem enviada, facilitando a comunicação bidirecional entre sistemas.

Método de Enviar por Json

Verbo HTTP: Post

Endpoint: https://SeuEndPoint.com.br

Parâmetros de saída


Parâmetro Obrigatório Formato Descrição
MensagemId Sim Int Identificação única da mensagem
CodigoIntegracao Sim String (50) Código fornecido na integração
NA Sim String (36) Número de origem da mensagem
NB Sim String (36) Número de destino da mensagem
MensagemEnviada Sim String (256) Texto da mensagem original enviada
MensagemRetorno Sim String (256) Texto da resposta recebida do destinatário
DataEnvio Sim yyyy/MM/ddTHH:mm:ss Data e hora em que a mensagem foi enviada
DataRetorno Sim yyyy/MM/ddTHH:mm:ss Data e hora em que a resposta foi recebida

Exemplo de visualização da resposta:


		   {
			MensagemId: {MensagemId},
			CodigoIntegracao: {CodigoIntegracao},
			NA: {NA},
			NB: {NB},
			MensagemEnviada: {MensagemEnviada},  String --Texto contendo a mensagem original Enviada
			MensagemRetorno: {MensagemRetorno},  String --Texto contendo a mensagem de Resposta do Destinatario	
			DataEnvio: {DataEnvio}, 	     Datetime --Data e hora de Envio do SMS
			DataRetorno: {DataRetorno}	     Datetime --Data e hora de Resposta do SMS
		   }

Tela de Gerenciamento:

URL: https://sms.talkcomm.com.br/ClienteWebhooks/List


Autenticação:

Descrição da imagem

Cadastro:

Descrição da imagem

Entre em contato : 55 11 4858 4444 | [email protected]