Integração utilizando Webphone próprio

Essa integração permite que você utilize o Webphone próprio para fazer chamadas telefônicas diretamente do seu CRM. Com essa integração, você pode fazer chamadas telefônicas, registrar chamadas, enviar mensagens de voz e muito mais.

Criação de uma nova conta

Primeiramente, você precisa criar uma nova conta que será única para a sua empresa. Para isso, acesse o Portal da Api4Com, preencha o formulário de cadastro e clique em "Criar conta".

Você também poder criar uma nova conta através da API. Para isso, utilize o seguinte código:

Os campos obrigatórios são:

• organization_name: Nome da empresa
• domain: Domínio da empresa na Api4Com, deve ser único e terminar com .api4com.com
• email: E-mail do usuário, deve ser único
• password: Senha do usuário
• phone: Número de telefone da empresa
• crm: CRM utilizado pela empresa
  • Opções: 'ActiveCampaign', 'Agendor', 'AppFacilita', 'ExactSalesSpotter', 'Groner', 'HubSpot', 'Kommo', 'MoskitCRM', 'NectarCRM', 'Pipedrive', 'Piperun', 'Ploomes', 'RDCRM', 'Salesflow', 'Salesforce', 'SharpSpring', 'Zendesk', 'ZohoCRM', 'Outros'
• user_quantity: Quantidade de usuários
  • Opções: '1-5', '6-10', '11-20', '21-50', '50+'

const axios = require('axios');
const url = 'https://api.api4com.com/api/v1/accounts/signup';
const payload = {
  organization_name: 'Nome da Empresa',
  domain: 'seudominio.api4com.com',
  email: 'email@usuario.com',
  password: 'senha123',
  phone: '+554833328530',
  crm: 'Outros',
  user_quantity: '1-5'
};
axios.post(url, payload).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});

Resposta de sucesso:

{
  "status": 201,
  "message": "Cadastro realizado com sucesso!"
}

Importante:

• Um email de confirmação será enviado para o email informado no cadastro. Para ativar a conta, clique no link de confirmação.

Criando um Token de Acesso que nunca expira

Para criar um Token de Acesso que nunca expira, utilize o seguinte código:

const axios = require('axios');
const url = 'https://api.api4com.com/api/v1/users/accessTokens';
const config = {
  headers: {
    'Authorization': '<token>'
  }
};
const payload = {
  ttl: -1
};
axios.post(url, payload, config).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});

Resposta de sucesso:

{
  "id": "YggyHfrLEHAWmKiUFbXsT93Tkw2xjwHUbwJ6mgw4Vz5YGubReFGw34HmhrhZDUBM",
  "ttl": -1,
  "created": "2025-01-01T00:00:00.000
}

Importante:

• O token de acesso gerado via Login deve ser enviado no cabeçalho da requisição, no campo Authorization.
• Guarde o token de acesso gerado, pois ele será necessário para fazer as requisições.

Configuração do Webhook

Para configurar o Webhook é necessário criar uma Integração de Usuário via API.

Segue um exemplo de como criar uma Integração de Usuário:

const axios = require('axios');
const url = 'https://api.api4com.com/api/v1/integrations';
const config = {
  headers: {
    'Authorization': '<token>'
  }
};
const payload = {
  gateway: 'integration-test',
  webhook: true,
  webhookConstraint: {
    metadata: {
      gateway: 'integration-test'
    }
  },
  metadata: {
    webhookUrl: 'https://seu-webhook.com/callback',
    webhookVersion: 'v1.4',
    webhookTypes: ['channel-hangup']
  }
};
axios.patch(url, payload, config).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});

Resposta de sucesso:

{
  "id": 123,
  "gateway": "integration-test",
  "webhook": true,
  "webhookConstraint": {
    "metadata": {
      "gateway": "integration-test"
    }
  },
  "metadata": {
    "webhookUrl": "https://seu-webhook.com/callback",
    "webhookVersion": "v1.4",
    "webhookTypes": ["channel-hangup"]
  }
}

Importante:

• O campo gateway deve ser preenchido com o nome do seu gateway.
• O campo webhookUrl deve ser preenchido com a URL do seu webhook.
• Somente as chamadas que atenderem as restrições do webhook serão enviadas para o webhook, ou seja, somente aquelas que possuam o mesmo valor no campo metadata.

Criando novos ramais para os usuários

Para criar novos ramais para os usuários, utilize a API de Ramais.

Segue um exemplo de como criar um novo ramal:

const axios = require('axios');
const url = 'https://api.api4com.com/api/v1/extensions';
const config = {
  headers: {
    'Authorization': '<token>'
  }
};
// Descobrir qual é o próximo ramal disponível
async function getNextAvailableExtension() {
  const POSSIBLE_EXTENSIONS = [...Array(99000).keys()].map(i => String(i + 1000))
  const urlExtensions = 'https://api.api4com.com/api/v1/extensions?filter=%7B%22fields%22%3A%7B%22ramal%22%3Atrue%7D%7D'
  const availableExtensions = await axios.get(urlExtensions, config).then(response => {
    return response.data.map(ext => ext.ramal)
  }).then(extensions => {
    return POSSIBLE_EXTENSIONS.filter(extension => !extensions.includes(extension))
  }).catch(error => console.error(error))
  if (availableExtensions.length > 0) {
    return availableExtensions.shift()
  } else {
    throw new Error('No available extensions')
  }
}
async function createExtension() {
  const payload = {
    ramal: await getNextAvailableExtension(),
    senha: 'PwDLooL',
    bina: '4833328530',
    first_name: 'Nome',
    last_name: 'do Usuário',
    email_address: 'email@usuario2.com',
    gravar_audio: 1
  }
  axios.post(url, payload, config).then(response => {
    console.log(response.data);
  }).catch(error => {
    console.error(error);
  });
};
createExtension();

Resposta de sucesso:

{
  "id": 123,
  "ramal": "1001",
  "senha": "PwDLooL",
  "bina": "4833328530",
  "first_name": "Nome",
  "last_name": "do Usuário 2",
  "email_address": "email@usuario2.com",
  "gravar_audio": 1
}

Importante:

• Para criar um ramal na conta, é necessário informar o token de autenticação no cabeçalho da requisição.
• O ramal precisa ser salvo do seu lado, relacionando o ramal com o usuário interno seu, esse valor é importante para fazer as chamadas.

Criando um Webphone

Para criar um Webphone, utilize a documentação do VoIP / SIP.

Importante:

• O Webphone deve ser configurado para utilizar o domínio da sua empresa na Api4Com.
• O Webphone deve ser configurado para utilizar o ramal e senha criado para cada usuário.
• O Webphone deve ser Singleton, ou seja, deve ter apenas uma instância por usuário. Caso novas instâncias sejam criadas, a anterior será desconectada.

Realizando uma chamada

Para realizar uma chamada, utilize o seguinte código:

const axios = require('axios');
const url = 'https://api.api4com.com/api/v1/dialer';
const config = {
  headers: {
    'Authorization': '<token>'
  }
};
const payload = {
  extension: '1000',
  phone: '+554833328530',
  metadata: {
    gateway: 'integration-test',
    userId: 123,
    entityId: 456
  }
};
axios.post(url, payload, config).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});

Resposta de sucesso:

{
  "id": "bdf199fa-f85b-4378-80cd-0ac28c1355e9",
  "message": "successfull"
}

Importante:

• O campo Authorization deve ser preenchido com o token de acesso gerado.
• O campo extension deve ser preenchido com o número do ramal do usuário que irá realizar a chamada, neste caso, o número do seu ramal, que você guardou ao instalar o Webphone.
• O campo phone deve ser preenchido com o número de telefone que você deseja ligar.
• O campo metadata deve ser preenchido com os dados que você deseja enviar para o webhook.

Recebendo o Webhook

Quando uma chamada é finalizada, o webhook é acionado e envia uma requisição POST para a URL configurada. O corpo da requisição é um JSON com as informações da chamada.

Segue um exemplo de webhook:

{
  "version": "v1.4",
  "eventType": "channel-hangup",
  "id": "2ee13fa4-975c-499d-bbb8-5177ff418316",
  "domain": "seudominio.api4com.com",
  "direction": "outbound",
  "caller": "1000",
  "called": "04833328530",
  "startedAt": "2025-01-01 00:00:00",
  "answeredAt": "2025-01-01 00:00:05",
  "endedAt": "2025-01-01 00:00:10",
  "duration": 5,
  "hangupCause": "NORMAL_CLEARING",
  "hangupCauseCode": "16",
  "recordUrl": "https://listener.api4com.com/files/listen/2ee13fa4-975c-499d-bbb8-5177ff418316.mp3",
  "metadata": {
    "gateway": "integration-test",
    "userId": 123,
    "entityId": 456
  }
}

Os campos retornados são:

• O campo version indica a versão do webhook.
• O campo eventType indica o tipo de evento.
• O campo id é o identificador da chamada.
• O campo domain é o domínio da empresa.
• O campo direction indica se a chamada é de entrada ou saída.
• O campo caller é o número do ramal que realizou a chamada.
• O campo called é o número de telefone que recebeu a chamada.
• O campo startedAt é a data e hora de início da chamada.
• O campo answeredAt é a data e hora que a chamada foi atendida.
• O campo endedAt é a data e hora que a chamada foi finalizada.
• O campo duration é a duração da chamada em segundos.
• O campo hangupCause é o motivo do desligamento da chamada.
• O campo hangupCauseCode é o código do motivo do desligamento da chamada.
• O campo recordUrl é a URL do arquivo de áudio da chamada.
• O campo metadata é um objeto com os dados enviados na requisição de chamada.

Próximos passos

Agora para continuar a integração, você pode:

• Realizar a chamada a partir do seu CRM executando o passo Realizando uma chamada.
• Receber as informações da chamada no seu webhook executando o passo Recebendo o Webhook e adicionar as informações no seu CRM.

Considerações finais

Neste guia, você aprendeu como integrar a Api4Com com o seu CRM utilizando o Webphone próprio. Com essa integração, você pode fazer chamadas telefônicas, registrar chamadas, enviar mensagens de voz e muito mais. Caso tenha alguma dúvida, entre em contato com o nosso suporte.

A documentação completa da Api4Com está disponível em https://docs.api4com.com.

Se você tiver alguma dúvida ou precisar de ajuda, entre em contato com o suporte da Api4Com.